Quickstart
AutoDoc is a platform that integrates with GitHub to automatically generate and host documentation for code repositories using AI assistance. The API exposes functionality for developers to interact with this system programmatically, including triggering documentation jobs, retrieving their status, publishing documents, and managing supporting features like custom domains and user feedback.
This quickstart focuses on the essential first steps for using the API: obtaining a product access token to serve as your API key and then performing a basic request to fetch data from the service. The process is designed to be straightforward for engineers integrating AutoDoc into their workflows or tools.
Obtain an API key
Product access tokens function as API keys for authenticating calls to the AutoDoc API.
These tokens are managed through a dedicated endpoint and are associated with specific scopes that control what actions they can perform.
To obtain a new token, you must send a POST request to the /tokens endpoint.
The request body is required to include a name field, which provides a label for the token, and a scopes field, which is an array of strings representing the permissions you wish to grant.
You may also provide an optional expiresAt field to specify when the token should no longer be valid.
The API will validate the request and, if successful, create the token record.
The response will return the full details of the access token, including its id, name, scopes, createdAt, and the secret token value.
Because the token value is only returned in this initial response, it is critical to save it immediately in a secure manner.
Do not expose the token in client-side code or public repositories.
With the token obtained, you can now use it for authenticated requests.
The precise way to pass the token in HTTP requests, including any required headers or formats, is described in the authentication documentation.
Note that the tokens endpoint is itself a protected route, so the initial request to create a token will also need to be authenticated using one of the supported methods, such as a Supabase JWT for user-scoped access.
Make your first request
After securing your access token, you can test the connection with a public endpoint or proceed to authenticated operations.
Public health check
Begin with the health check by issuing a GET request to /health.
This endpoint is available without any authentication and serves as a basic connectivity test.
It returns a simple object that includes the status field, which should read "ok" if the service is running correctly, and a timestamp field formatted as a date-time string.
Calling this endpoint first allows you to confirm that the base URL is correct and that your HTTP client is configured properly before adding authentication headers.
Retrieving job information
For an example of retrieving data that may be scoped to your access, send a GET request to /jobs.
This lists documentation generation jobs that have been created in the system.
You can refine the results using query parameters.
The limit parameter controls how many jobs are returned at once, with a default of 50 and a maximum of 100.
The status parameter lets you filter to only jobs in a particular state, using one of the allowed values: pending, processing, completed, and failed.
The API responds with a JSON array.
Each element in the array is a job record that conforms to the Job schema defined in the API specification.
The schema specifies the following properties for each job:
id, a required unique identifier.repository, the full repository identifier.status, indicating the job's current state.prUrl, which may contain a link to a pull request or be absent.branch, the relevant branch name or absent.createdAtandupdatedAt, both in date-time format.error, which provides details if the job encountered a failure.
You can use the information from the response to understand the state of documentation tasks.
If authentication is needed for this endpoint in your context, include your access token as outlined in the authentication documentation.
To get details on a single job, append the job ID to the path as /jobs/{id} and issue another GET request.
Interpreting the response
The API uses standard JSON for both success and error cases.
When a request succeeds, the body contains the data relevant to the operation, such as the array of jobs or the health status object.
Error responses follow a uniform structure with three fields: error for a short code, a message for a human-readable explanation, and the statusCode.
This consistent format makes it easier to handle issues in your client code.
For a full list of possible errors and their meanings, consult the errors documentation.
Next steps
With the ability to create tokens and fetch basic data, you can now explore additional endpoints.
For instance, the jobs endpoint also supports creating new jobs via POST requests, which can initiate the documentation generation process for a specified repository.
Other areas include document management at /docs for publishing and updating hosted documentation, domain configuration, and collecting page feedback.
The OpenAPI specification file contains the complete, machine-readable description of all endpoints, parameters, request bodies, and response schemas.
You can use this to build client code or to discover the full capabilities of the API.
If you encounter issues during these steps, the errors page provides additional troubleshooting information.
This completes the minimal end-to-end example.