API Reference

The v1 API covers the Contextual Enrichment Engine, durable jobs, account usage, feed utilities, projects, 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

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.

Account: Health, Usage.

Utilities: Detect language, Agentic readiness, Review quality.

Feeds and projects: List feeds, Get a feed, List projects, Get a project.

Webhooks: List, Create, Get, Update, Delete, Deliveries.

Content types

Use these values in the contentTypes array for POST /enrichment/content and POST /enrichment/pipeline.

A value that is not in this table is skipped rather than rejected, and is listed in skippedContentTypes (on a synchronous response, or on the job's result) so you can see it was not generated or charged. image-alt needs at least one product image with a public URL.

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.

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:

Success responses use { "data": ... } or the documented response shape for that endpoint.

Error codes

PROJECT_ID_REQUIRED

{
  "error": {
    "code": "PROJECT_ID_REQUIRED",
    "message": "This endpoint returns project-scoped data. Pass ?projectId=<id>, or use a key pinned to a project."
  }
}

Why you may be seeing this now. GET /feeds and GET /feeds/{id} used to answer an account-wide key with no projectId by merging rows from every project on the account. Nothing in the response said which project each row came from, so there was no safe way to read it. They now ask you to name one.

Two ways to fix it, both one-time:

• add ?projectId=<id> to the request. Ids come from GET /projects.
• or pin the key to a project in Settings, Developer console, Keys, and leave the parameter off.

PROJECT_SCOPE_MISMATCH

{
  "error": {
    "code": "PROJECT_SCOPE_MISMATCH",
    "message": "This API key is scoped to a different project."
  }
}

A pinned key may only act on its own project. Use an account-wide key, or a key pinned to the project you are addressing.