---
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) |