The basics
How authentication works, the IDs you'll see in every response, and the rules for usage, retention, webhooks and errors.
Authentication
Every request must include your API key in the X-API-Key header. If the header is missing or the key is invalid, the API returns 401.
X-API-Key: your_api_keyDon't have a key yet? Request API access, then create keys in your AnchorGrid account.
Key format, plans and rate limits: see Authentication in detail.
Key terms
You'll see these names in requests and responses across the API.
document_idReturned when you upload a PDF with POST /v1/documents. Pass it to any drawing or spec analysis. Expires after your plan's retention window.
job_idReturned right away (202) when you start an analysis. Use it with GET /v1/jobs/{job_id} until the status is complete or failed.
poll_urlA relative path such as /v1/jobs/<uuid>, included in every 202 response. Add https://api.anchorgrid.ai in front to get the full URL.
webhook_urlOptional field on analysis requests. When you include it, the API sends the completed job to that URL.
Usage
Analyses are counted in two units. Element detection: finding one element type (doors, toilets, rooms or wall materials) on one sheet is one element detection, however many it finds. Document indexing: classification, elevation detection and schedule extraction count each page they read (classification skips pages without a text layer and doesn't count them); reading a spec's table of contents counts the pages it reads, at most the first 40; extracting spec sections counts the pages of the sections it returns. Use page_numbers to limit which pages an analysis reads. Failed and canceled jobs aren't counted.
| Analysis | Counts as |
|---|---|
| Detect doors | Element detection, per sheet |
| Detect toilets | Element detection, per sheet |
| Detect rooms | Element detection, per sheet |
| Detect wall materials | Element detection, per sheet |
| Classify drawings | Document indexing, per page read |
| Detect elevations | Document indexing, per page read |
| Extract schedules | Document indexing, per page scanned |
| Read a spec’s table of contents | Document indexing, per page read (up to 40) |
| Extract spec sections | Document indexing, per page of the sections extracted |
Uploading a document and checking or canceling a job are not counted.
For prices and what each plan includes, see Pricing.
Document retention
A document_id stays valid for your plan's retention window. If it has expired, upload the PDF again to get a new one.
Webhooks
Add webhook_url to any analysis request and the API sends the completed job to that URL, so you don't need to keep checking. Webhooks are available on developer, pro and enterprise plans.
Errors
An accepted analysis request returns 202. A job that runs but can't produce a result reports failed as its status.
| What you see | What it means |
|---|---|
| 202 Accepted | The analysis is queued. Use job_id or poll_url to get the result. |
| 401 Unauthorized | The X-API-Key header is missing or the key is invalid. Check the header name. |
Job status failed | The job finished without a result. This comes back from the job endpoint, not as an HTTP error. |
Every status code and the error response format: see Errors in detail.