API Reference
Overview of the ACE v1 API, authentication, scopes, jobs, and errors.
The v1 API covers the Contextual Enrichment Engine, durable jobs, account usage, feed utilities, projects, experiments, and webhooks. Each endpoint has its own reference page in this section with parameters, schemas, request samples, and a live request panel. This page covers the parts that apply across all of them.
Base URL
https://ace.authoritas.com/api/v1
All paths below are relative to that base. For a machine readable description, GET /api/v1/openapi returns the full OpenAPI 3.0 spec.
Authentication
Every endpoint that requires auth accepts an API key in either header:
Authorization: Bearer <your-api-key>X-API-Key: <your-api-key>
No key is needed for GET /api/v1/health or GET /api/v1/openapi. Create and manage keys under Settings, Developer console, Keys. See API Keys for details.
Scopes
| Scope | Endpoints unlocked |
|---|---|
enrichment:read | GET /jobs, GET /jobs/{id}, GET /jobs/{id}/results, GET /usage, GET /feeds, GET /projects, GET /experiments |
enrichment:write | Everything above, plus POST /enrichment/rules, POST /enrichment/content, POST /enrichment/pipeline, POST /jobs/{id}/cancel |
utils:read | POST /utils/language, POST /utils/agentic-readiness, POST /utils/review-quality |
webhooks:read | GET /webhooks, GET /webhooks/{id}, GET /webhooks/{id}/deliveries |
webhooks:write | Everything above, plus create, update, and delete webhooks |
admin | Every v1 endpoint. Grants all other scopes. |
New keys get enrichment:read, enrichment:write, and utils:read by default.
Endpoints
Contextual Enrichment Engine: Generate contextual rules, Generate rules-grounded content, Run the full pipeline.
Jobs: List jobs, Get a job, Get job results, Cancel a job.
Utilities: Detect language, Agentic readiness, Review quality.
Feeds and projects: List feeds, Get a feed, List projects, Get a project.
Experiments: List, Create, Get, Update, Delete.
Webhooks: List, Create, Get, Update, Delete, Deliveries.
Content types
Use these values in the contentTypes array for POST /enrichment/content and POST /enrichment/pipeline.
| Content type | API value |
|---|---|
| Product description | product-description |
| Meta tags and SEO | meta-tags |
| Enhanced JSON-LD schema | jsonld-schema |
| IRL scenario cards | irl-scenarios |
| Internal linking recommendations | internal-links |
| Google Shopping feed fields | google-shopping |
| Agentic Commerce feed fields | agentic-commerce |
| Microsoft Shopping feed fields | microsoft-shopping |
| Shopify feed fields | shopify |
Synchronous and asynchronous requests
POST /enrichment/rules returns its result inline. POST /enrichment/content and POST /enrichment/pipeline decide based on how much work you asked for: a small inline set runs immediately, and anything larger returns 202 with a job envelope. Send "mode": "async" to force a job, or "mode": "sync" to require an inline result.
Poll a job with GET /jobs/{id}, or subscribe to webhooks and skip polling.
Idempotency
Send an Idempotency-Key header on a write to make a retry safe. A repeat within the retention window returns the original job instead of starting a second one.
Key management
These endpoints manage API keys for the currently logged in user. They use session (cookie) auth, not an API key, so call them from your app or from a script that shares the browser session.
| Method | Path | Purpose |
|---|---|---|
| GET | /api/keys | List the current user's keys (metadata only). |
| POST | /api/keys | Create a key. Body: name (required), optional scopes, rate_limit_per_minute, expires_at. The plain key is returned only on create. |
| GET | /api/keys/[id] | Get one key by ID (metadata only). |
| PATCH | /api/keys/[id] | Update a key (name, scopes, rate limit, expiry, active state). |
| DELETE | /api/keys/[id] | Revoke and delete the key. |
Rate limits
Each key has a configurable requests per minute limit. When exceeded, the API returns 429 with Retry-After and X-RateLimit-* headers. Set the limit when creating or editing the key.
Errors
Errors use the shape { "error": { "code": "...", "message": "...", "details": ... } } with these HTTP statuses:
| Status | Meaning |
|---|---|
| 400 | Invalid request or validation error |
| 401 | Missing or invalid API key |
| 402 | Insufficient credits, test quota exhausted, or subscription required |
| 403 | Forbidden, for example a missing scope |
| 404 | No such resource, or it belongs to another account |
| 429 | Rate limit exceeded |
| 500 | Server error |
Success responses use { "data": ... } or the documented response shape for that endpoint.