File size: 2,776 Bytes
f8b48da | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 | ---
doc_id: api-reference
title: API Reference
version: 1.0
module: api
last_updated: 2026-09-12
---
## API Terminal (#api-terminal)
All API requests must use HTTPS.
```text
https://api.askmydocs.example/v1
```
The API is versioned in the URL path. The current version is v1. Breaking changes are announced at least 6 months in advance.
## Authentication (#authentication)
Every request must include an Authorization header with a bearer token:
```http
GET /v1/projects HTTP/1.1
Host: api.askmydocs.example
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...
```
Tokens expire after 60 minutes. Use the refresh flow before expiry to avoid 401 responses.
## Pagination (#pagination)
List endpoints paginate using cursor-based pagination. The response contains a ``next_cursor`` field; pass it as the ``cursor`` parameter to fetch the next page.
| Parameter | Type | Description |
| --- | --- | --- |
| limit | int | Max items per page (1-100, default 20) |
| cursor | string | Opaque pagination cursor |
## Idempotency (#idempotency)
Write endpoints accept an ``Idempotency-Key`` header. If a request with the same key is retried, the server returns the original response without applying the change twice.
Idempotency keys are honored for 24 hours. Use UUID v4 values.
## Rate Limits (#rate-limits)
The default rate limit is 100 requests per minute.Short bursts up to 300 requests per minute are allowed.
Rate limits apply per API key, per endpoint. Responses include ``X-RateLimit-Limit``, ``X-RateLimit-Remaining``, and ``X-RateLimit-Reset`` headers.
> **Warning**: Hitting the rate limit returns HTTP 429 with a ``Retry-After`` header. Respect the header; do not retry immediately.
## Webhooks (#webhooks)
Webhooks notify your system about events such as document processed, document failed, and ingestion complete.
Each delivery is signed with HMAC-SHA256 signature using the webhook secret. The signature is sent in the ``X-AskMyDocs-Signature`` header as ``t=<timestamp>,v1=<hex>``.
Delivery is retried up to 5 retries, exponential backoff, max 10 minutes.
```python
# Verify a webhook signature
import hashlib, hmac
def verify(secret, body, header):
timestamp, signature = header.split(',')
digest = hmac.new(secret.encode(), f'{timestamp}.{body}'.encode(), hashlib.sha256).hexdigest()
return hmac.compare_digest(digest, signature.split('=')[1])
```
## Common Headers (#common-headers)
| Header | Required | Description |
| --- | --- | --- |
| Authorization | Yes | Bearer token |
| Idempotency-Key | Write ops | Prevent duplicate writes |
| X-Request-ID | No | Correlate logs; echoed in response |
| Accept-Version | No | Pin API version (default v1) |
|