Skip to content
Amber

Docs

API reference

The HTTP API under /api/v1: authentication, errors and endpoints.

The HTTP API lives under /api/v1. It is described by OpenAPI at /api/v1/openapi.json, and this page is rendered from that description, so it lists exactly what the API serves. An interactive version is at /api/v1/docs.

#Authentication

The public catalog endpoints need no authentication. Everything else takes an Amber API key, scoped to one Workspace, sent as a bearer token:

curl -H "Authorization: Bearer $AMBER_API_KEY" https://amber.trycoredepth.com/api/v1/wallet

Create keys in your Workspace settings or with the CLI sign-in flow. A key is shown once and stored only as a hash. Every request is scoped by Workspace membership.

#Errors and pagination

Errors are JSON:

{ "error": { "code": "quote_expired", "message": "This Quote has expired." } }

List endpoints are paginated with cursors: pass limit (up to 100) and, from a previous page's next_cursor, cursor. The last page has a next_cursor of null. Rate limits apply per API key and per IP, and are strictest on /quotes.

#Catalog

The public Benchmarks, Models and curated Model Configurations. No authentication, and responses may be cached for a minute.

  • GET
    /api/v1/catalog/agents

    List the Agent Versions, newest first Public. Returns Page_CatalogAgentVersionOut_.

    include_deprecated query
    boolean Also versions retired from new Jobs.
    limit query
    integer Items per page.
    cursor query
    string | null From a previous page's next_cursor.
  • GET
    /api/v1/catalog/benchmarks

    List the public Benchmarks Public. Returns Page_BenchmarkOut_.

    featured query
    boolean | null Only (or never) featured ones.
    task_kind query
    TaskKind | null Has a version of this kind.
    source query
    BenchmarkSource | null Has a version from here.
    q query
    string | null Search name, slug and description.
    limit query
    integer Items per page.
    cursor query
    string | null From a previous page's next_cursor.
  • GET
    /api/v1/catalog/benchmarks/{slug}

    One public Benchmark, with its latest version and typical costs Public. Returns BenchmarkDetailOut.

    slug path, required
    string
  • GET
    /api/v1/catalog/benchmarks/{slug}/versions

    A Benchmark's version history, newest first Public. Returns Page_BenchmarkVersionOut_.

    slug path, required
    string
    limit query
    integer Items per page.
    cursor query
    string | null From a previous page's next_cursor.
  • GET
    /api/v1/catalog/model-configurations

    List the curated Model Configurations Public. Returns Page_ConfigurationOut_.

    model query
    string | null Slug of the Model.
    developer query
    string | null Who built the Model.
    q query
    string | null Search slug and name.
    include_archived query
    boolean Also those retired from new Jobs.
    limit query
    integer Items per page.
    cursor query
    string | null From a previous page's next_cursor.
  • GET
    /api/v1/catalog/model-configurations/{slug}

    One curated Model Configuration Public. Returns ConfigurationOut.

    slug path, required
    string
  • GET
    /api/v1/catalog/models

    List the Models, with their Providers and prices Public. Returns Page_ModelOut_.

    developer query
    string | null Who built it, e.g. `anthropic`.
    q query
    string | null Search slug, name and OpenRouter id.
    curated query
    boolean | null Only (or never) Models with a curated Model Configuration.
    limit query
    integer Items per page.
    cursor query
    string | null From a previous page's next_cursor.
  • GET
    /api/v1/catalog/models/{slug}

    One Model, with every Provider that serves it Public. Returns ModelOut.

    slug path, required
    string

#Health

  • GET
    /api/v1/healthz

    Liveness probe Public. Returns Health.

  • GET
    /api/v1/readyz

    Readiness probe: the database answers Public. Returns Health.

#Other endpoints

Groups appear here as the API gains them: Workspaces, API keys, Quotes and Jobs, Results, the Wallet, private Benchmarks and guided authoring.

Admin

  • GET
    /api/v1/admin/agents

    List Agents with every Agent Version Returns Page_AgentOut_.

    limit query
    integer Items per page.
    cursor query
    string | null From a previous page's next_cursor.
  • POST
    /api/v1/admin/agents

    Create an Agent Returns AgentOut.

  • POST
    /api/v1/admin/agents/{agent_slug}/versions

    Publish an immutable Agent Version Returns AgentVersionOut.

    agent_slug path, required
    string
  • POST
    /api/v1/admin/agents/{agent_slug}/versions/{version}/deprecate

    Stop offering an Agent Version for new Jobs Returns AgentVersionOut.

    agent_slug path, required
    string
    version path, required
    string
  • GET
    /api/v1/admin/audit-logs

    The audit log, newest first Returns Page_AuditLogOut_.

    workspace_id query
    string (uuid) | null
    action query
    string | null An action (`wallet.credit`) or its prefix (`wallet.`).
    actor_id query
    string | null
    limit query
    integer Items per page.
    cursor query
    string | null From a previous page's next_cursor.
  • GET
    /api/v1/admin/benchmarks

    List the public Benchmarks, hidden ones too Returns Page_AdminBenchmarkOut_.

    q query
    string | null Search slug and name.
    featured query
    boolean | null
    hidden query
    boolean | null
    limit query
    integer Items per page.
    cursor query
    string | null From a previous page's next_cursor.
  • PATCH
    /api/v1/admin/benchmarks/{slug}

    Feature, hide, or set the Quote prior of a Benchmark Returns AdminBenchmarkOut.

    slug path, required
    string
  • GET
    /api/v1/admin/jobs

    List Jobs of every Workspace, newest first Returns Page_AdminJobOut_.

    state query
    JobState | null
    workspace_id query
    string (uuid) | null
    purpose query
    JobPurpose | null
    active query
    boolean | null Only Jobs that haven't finished (or only those that have).
    limit query
    integer Items per page.
    cursor query
    string | null From a previous page's next_cursor.
  • POST
    /api/v1/admin/jobs/{job_id}/cancel

    Cancel a Job Returns AdminJobOut.

    job_id path, required
    string (uuid)
  • GET
    /api/v1/admin/kill-switch

    Whether new Trials are stopped Returns KillSwitchOut.

  • PUT
    /api/v1/admin/kill-switch

    Stop (or allow again) new Trials everywhere Returns KillSwitchOut.

  • POST
    /api/v1/admin/model-configurations

    Publish a curated Model Configuration Returns ConfigurationOut.

  • POST
    /api/v1/admin/model-configurations/{slug}/archive

    Retire a curated Model Configuration from new Jobs Returns ConfigurationOut.

    slug path, required
    string
  • GET
    /api/v1/admin/model-sync

    How the last price sync went Returns ModelSyncStatus.

  • POST
    /api/v1/admin/model-sync

    Start a price sync from OpenRouter Returns ModelSyncStatus.

  • GET
    /api/v1/admin/platform-settings

    The platform settings Returns PlatformSettingsOut.

  • PATCH
    /api/v1/admin/platform-settings

    Change platform settings Returns PlatformSettingsOut.

  • POST
    /api/v1/admin/private-benchmarks/uploads

    Upload Harbor Task folders into a Workspace (only if it allows staff access) Returns UploadOut.

    workspace_id query, required
    string (uuid) The Workspace to upload into.
  • GET
    /api/v1/admin/reconciliation

    LiteLLM spend against Ledger charges, by Provider and day Returns ReconciliationReport.

    start query
    string (date) | null First UTC day. Default: 6 days before end.
    end query
    string (date) | null Last UTC day. Default: today.
    tolerance_micros query
    integer Differences up to this many micro-USD still reconcile.
  • GET
    /api/v1/admin/status

    The platform at a glance: settings and load Returns PlatformStatus.

  • GET
    /api/v1/admin/workspaces

    List Workspaces, newest first Returns Page_AdminWorkspaceOut_.

    q query
    string | null Search name, address, or a member's email or user ID.
    include_archived query
    boolean Also deleted Workspaces.
    limit query
    integer Items per page.
    cursor query
    string | null From a previous page's next_cursor.
  • GET
    /api/v1/admin/workspaces/{workspace_id}

    One Workspace: members, Wallet and Jobs Returns AdminWorkspaceDetailOut.

    workspace_id path, required
    string (uuid)
  • POST
    /api/v1/admin/workspaces/{workspace_id}/adjustments

    Adjust the Wallet Returns LedgerEntryOut.

    workspace_id path, required
    string (uuid)
  • POST
    /api/v1/admin/workspaces/{workspace_id}/credits

    Add credit Returns LedgerEntryOut.

    workspace_id path, required
    string (uuid)
  • GET
    /api/v1/admin/workspaces/{workspace_id}/ledger

    A Workspace's Wallet ledger, newest first Returns Page_LedgerEntryOut_.

    workspace_id path, required
    string (uuid)
    limit query
    integer Items per page.
    cursor query
    string | null From a previous page's next_cursor.
  • GET
    /api/v1/admin/workspaces/{workspace_id}/private-benchmarks

    A Workspace's private Benchmarks (only if it allows staff access) Returns PrivateBenchmarkOut[].

    workspace_id path, required
    string (uuid)
  • POST
    /api/v1/admin/workspaces/{workspace_id}/private-benchmarks

    Publish a Benchmark Version into a Workspace (only if it allows staff access) Returns PublishedOut.

    workspace_id path, required
    string (uuid)
  • GET
    /api/v1/admin/workspaces/{workspace_id}/private-benchmarks/uploads

    A Workspace's uploads (only if it allows staff access) Returns Page_UploadOut_.

    workspace_id path, required
    string (uuid)
    limit query
    integer Items per page.
    cursor query
    string | null From a previous page's next_cursor.
  • GET
    /api/v1/admin/workspaces/{workspace_id}/private-benchmarks/uploads/{upload_id}

    One of a Workspace's uploads (only if it allows staff access) Returns UploadOut.

    workspace_id path, required
    string (uuid)
    upload_id path, required
    string (uuid)
  • POST
    /api/v1/admin/workspaces/{workspace_id}/private-benchmarks/uploads/{upload_id}/publish

    Publish an upload's validated Tasks (only if the Workspace allows staff access) Returns UploadOut.

    workspace_id path, required
    string (uuid)
    upload_id path, required
    string (uuid)
  • POST
    /api/v1/admin/workspaces/{workspace_id}/private-benchmarks/uploads/{upload_id}/validate

    Accept an upload's validation Quote (only if the Workspace allows staff access) Returns UploadOut.

    workspace_id path, required
    string (uuid)
    upload_id path, required
    string (uuid)

Api keys

  • GET
    /api/v1/api-keys

    List the Workspace's API keys Returns Page_ApiKeyOut_.

    limit query
    integer Items per page.
    cursor query
    string | null From a previous page's next_cursor.
    X-Amber-Workspace header
    string | null Workspace ID or slug; defaults to your personal Workspace.
  • POST
    /api/v1/api-keys

    Create an API key Returns CreatedApiKey.

    X-Amber-Workspace header
    string | null Workspace ID or slug; defaults to your personal Workspace.
  • DELETE
    /api/v1/api-keys/{key_id}

    Revoke an API key

    key_id path, required
    string (uuid)
    X-Amber-Workspace header
    string | null Workspace ID or slug; defaults to your personal Workspace.

Authoring

  • GET
    /api/v1/authoring/sessions

    List the Workspace's authoring sessions Returns Page_AuthoringSessionSummaryOut_.

    limit query
    integer Items per page.
    cursor query
    string | null From a previous page's next_cursor.
    X-Amber-Workspace header
    string | null Workspace ID or slug; defaults to your personal Workspace.
  • POST
    /api/v1/authoring/sessions

    Start a guided authoring session (and get its Quote) Returns AuthoringSessionOut.

    X-Amber-Workspace header
    string | null Workspace ID or slug; defaults to your personal Workspace.
  • GET
    /api/v1/authoring/sessions/{session_id}

    Get an authoring session and its drafts Returns AuthoringSessionOut.

    session_id path, required
    string (uuid)
    X-Amber-Workspace header
    string | null Workspace ID or slug; defaults to your personal Workspace.
  • PUT
    /api/v1/authoring/sessions/{session_id}/files/{path}

    Write a file of a draft Returns AuthoringSessionOut.

    session_id path, required
    string (uuid)
    path path, required
    string
    X-Amber-Workspace header
    string | null Workspace ID or slug; defaults to your personal Workspace.
  • DELETE
    /api/v1/authoring/sessions/{session_id}/files/{path}

    Remove a file of a draft Returns AuthoringSessionOut.

    session_id path, required
    string (uuid)
    path path, required
    string
    X-Amber-Workspace header
    string | null Workspace ID or slug; defaults to your personal Workspace.
  • POST
    /api/v1/authoring/sessions/{session_id}/publish

    Publish the drafts that passed as a private Benchmark Version Returns AuthoringSessionOut.

    session_id path, required
    string (uuid)
    X-Amber-Workspace header
    string | null Workspace ID or slug; defaults to your personal Workspace.
  • POST
    /api/v1/authoring/sessions/{session_id}/validate

    Quote revalidating the edited drafts Returns AuthoringSessionOut.

    session_id path, required
    string (uuid)
    X-Amber-Workspace header
    string | null Workspace ID or slug; defaults to your personal Workspace.
  • POST
    /api/v1/authoring/snapshots

    Upload a repository snapshot for an authoring session Returns AuthoringSnapshotOut.

    X-Amber-Workspace header
    string | null Workspace ID or slug; defaults to your personal Workspace.

Cli

  • POST
    /api/v1/cli/device-codes

    Start a CLI login Public. Returns DeviceCodeCreated.

  • GET
    /api/v1/cli/device-codes/{user_code}

    Poll a CLI login Public. Returns DeviceCodePoll.

    user_code path, required
    string
    X-Device-Code header
    string | null
  • POST
    /api/v1/cli/device-codes/{user_code}/approve

    Approve a CLI login Returns DeviceCodeApproved.

    user_code path, required
    string
  • POST
    /api/v1/cli/device-codes/{user_code}/deny

    Deny a CLI login

    user_code path, required
    string
  • GET
    /api/v1/cli/device-codes/{user_code}/details

    What a CLI login asks for Returns DeviceCodeDetails.

    user_code path, required
    string

Results

  • GET
    /api/v1/comparisons

    Compare Model Configurations Returns ComparisonOut.

    job_ids query, required
    string (uuid)[] The Jobs to compare (repeat the parameter); their top-ups are included.
    benchmark_version query
    string (uuid) | null The Benchmark Version to compare on (default: the group with the most Model Configurations).
    agent_version query
    string (uuid) | null The Agent Version to compare on.
    X-Amber-Workspace header
    string | null Workspace ID or slug; defaults to your personal Workspace.
  • GET
    /api/v1/jobs/{job_id}/export

    Export a Job's results

    job_id path, required
    string (uuid)
    format query
    ExportFormat `json`, `csv` or `html`.
    X-Amber-Workspace header
    string | null Workspace ID or slug; defaults to your personal Workspace.
  • DELETE
    /api/v1/jobs/{job_id}/transcripts

    Delete a Job's transcripts Returns JobOut.

    job_id path, required
    string (uuid)
    X-Amber-Workspace header
    string | null Workspace ID or slug; defaults to your personal Workspace.
  • GET
    /api/v1/trials/{trial_id}

    Get a Trial Returns TrialDetailOut.

    trial_id path, required
    string (uuid)
    X-Amber-Workspace header
    string | null Workspace ID or slug; defaults to your personal Workspace.
  • GET
    /api/v1/trials/{trial_id}/transcript

    Get a Trial's transcript Returns TranscriptOut.

    trial_id path, required
    string (uuid)
    attempt query
    integer | null Which attempt (default: the last one).
    X-Amber-Workspace header
    string | null Workspace ID or slug; defaults to your personal Workspace.

Jobs

  • GET
    /api/v1/jobs

    List the Workspace's Jobs Returns Page_JobOut_.

    state query
    JobState | null Only Jobs in this state.
    limit query
    integer Items per page.
    cursor query
    string | null From a previous page's next_cursor.
    X-Amber-Workspace header
    string | null Workspace ID or slug; defaults to your personal Workspace.
  • POST
    /api/v1/jobs

    Start a Job from a Quote Returns JobOut.

    X-Amber-Workspace header
    string | null Workspace ID or slug; defaults to your personal Workspace.
  • GET
    /api/v1/jobs/{job_id}

    Get a Job Returns JobOut.

    job_id path, required
    string (uuid)
    X-Amber-Workspace header
    string | null Workspace ID or slug; defaults to your personal Workspace.
  • POST
    /api/v1/jobs/{job_id}/cancel

    Cancel a Job Returns JobOut.

    job_id path, required
    string (uuid)
    X-Amber-Workspace header
    string | null Workspace ID or slug; defaults to your personal Workspace.
  • GET
    /api/v1/jobs/{job_id}/events

    Follow a Job's progress (server-sent events)

    job_id path, required
    string (uuid)
    X-Amber-Workspace header
    string | null Workspace ID or slug; defaults to your personal Workspace.
  • GET
    /api/v1/jobs/{job_id}/trials

    List a Job's Trials Returns Page_TrialOut_.

    job_id path, required
    string (uuid)
    status query
    TrialStatus | null Only Trials in this status.
    limit query
    integer Items per page.
    cursor query
    string | null From a previous page's next_cursor.
    X-Amber-Workspace header
    string | null Workspace ID or slug; defaults to your personal Workspace.

Me

  • GET
    /api/v1/me

    The caller and the Workspaces they can use Returns Me.

Model configurations

  • GET
    /api/v1/model-configurations

    List the Workspace's custom Model Configurations Returns Page_ConfigurationOut_.

    include_archived query
    boolean Also those retired from new Jobs.
    limit query
    integer Items per page.
    cursor query
    string | null From a previous page's next_cursor.
    X-Amber-Workspace header
    string | null Workspace ID or slug; defaults to your personal Workspace.
  • POST
    /api/v1/model-configurations

    Create a custom Model Configuration Returns ConfigurationOut.

    X-Amber-Workspace header
    string | null Workspace ID or slug; defaults to your personal Workspace.
  • GET
    /api/v1/model-configurations/{slug}

    One of the Workspace's custom Model Configurations Returns ConfigurationOut.

    slug path, required
    string
    X-Amber-Workspace header
    string | null Workspace ID or slug; defaults to your personal Workspace.
  • DELETE
    /api/v1/model-configurations/{slug}

    Archive a custom Model Configuration Returns ConfigurationOut.

    slug path, required
    string
    X-Amber-Workspace header
    string | null Workspace ID or slug; defaults to your personal Workspace.

Private benchmarks

  • GET
    /api/v1/private-benchmarks

    List the Workspace's private Benchmarks Returns Page_BenchmarkOut_.

    limit query
    integer Items per page.
    cursor query
    string | null From a previous page's next_cursor.
    X-Amber-Workspace header
    string | null Workspace ID or slug; defaults to your personal Workspace.
  • GET
    /api/v1/private-benchmarks/uploads

    List the Workspace's uploads Returns Page_UploadOut_.

    limit query
    integer Items per page.
    cursor query
    string | null From a previous page's next_cursor.
    X-Amber-Workspace header
    string | null Workspace ID or slug; defaults to your personal Workspace.
  • POST
    /api/v1/private-benchmarks/uploads

    Upload Harbor Task folders for a private Benchmark Returns UploadOut.

    X-Amber-Workspace header
    string | null Workspace ID or slug; defaults to your personal Workspace.
  • GET
    /api/v1/private-benchmarks/uploads/{upload_id}

    Get an upload and its validation Returns UploadOut.

    upload_id path, required
    string (uuid)
    X-Amber-Workspace header
    string | null Workspace ID or slug; defaults to your personal Workspace.
  • GET
    /api/v1/private-benchmarks/{slug}/versions

    List a private Benchmark's versions Returns Page_BenchmarkVersionOut_.

    slug path, required
    string
    limit query
    integer Items per page.
    cursor query
    string | null From a previous page's next_cursor.
    X-Amber-Workspace header
    string | null Workspace ID or slug; defaults to your personal Workspace.
  • POST
    /api/v1/private-benchmarks/{upload_id}/publish

    Publish an upload's validated Tasks as a private Benchmark Version Returns UploadOut.

    upload_id path, required
    string (uuid)
    X-Amber-Workspace header
    string | null Workspace ID or slug; defaults to your personal Workspace.

Quotes

  • POST
    /api/v1/quotes

    Quote a Job, or a top-up of one Returns QuoteOut.

    X-Amber-Workspace header
    string | null Workspace ID or slug; defaults to your personal Workspace.
  • GET
    /api/v1/quotes/{quote_id}

    One of the Workspace's Quotes Returns QuoteOut.

    quote_id path, required
    string (uuid)
    X-Amber-Workspace header
    string | null Workspace ID or slug; defaults to your personal Workspace.

Wallet

  • GET
    /api/v1/wallet

    The Workspace's Wallet: balance, reservations and credit Returns WalletDetailOut.

    X-Amber-Workspace header
    string | null Workspace ID or slug; defaults to your personal Workspace.
  • GET
    /api/v1/wallet/ledger

    The Wallet's ledger, newest first Returns Page_WalletLedgerEntryOut_.

    limit query
    integer Items per page.
    cursor query
    string | null From a previous page's next_cursor.
    X-Amber-Workspace header
    string | null Workspace ID or slug; defaults to your personal Workspace.

Workspaces

  • GET
    /api/v1/workspaces

    List your Workspaces Returns Page_WorkspaceOut_.

    limit query
    integer Items per page.
    cursor query
    string | null From a previous page's next_cursor.
  • POST
    /api/v1/workspaces

    Create a Workspace Returns WorkspaceOut.

  • GET
    /api/v1/workspaces/{workspace_id}

    Get a Workspace Returns WorkspaceOut.

    workspace_id path, required
    string (uuid)
  • PATCH
    /api/v1/workspaces/{workspace_id}

    Rename a Workspace or toggle staff access Returns WorkspaceOut.

    workspace_id path, required
    string (uuid)
  • DELETE
    /api/v1/workspaces/{workspace_id}

    Delete a Workspace

    workspace_id path, required
    string (uuid)
  • GET
    /api/v1/workspaces/{workspace_id}/provider-policy

    Get the Provider policy Returns ProviderPolicy.

    workspace_id path, required
    string (uuid)
  • PUT
    /api/v1/workspaces/{workspace_id}/provider-policy

    Set the Provider policy Returns ProviderPolicy.

    workspace_id path, required
    string (uuid)

Members

  • GET
    /api/v1/workspaces/{workspace_id}/invites

    List pending invites Returns Page_InviteOut_.

    workspace_id path, required
    string (uuid)
    limit query
    integer Items per page.
    cursor query
    string | null From a previous page's next_cursor.
  • POST
    /api/v1/workspaces/{workspace_id}/invites

    Invite someone by email Returns InviteOut.

    workspace_id path, required
    string (uuid)
  • DELETE
    /api/v1/workspaces/{workspace_id}/invites/{invite_id}

    Revoke an invite

    invite_id path, required
    string (uuid)
    workspace_id path, required
    string (uuid)
  • GET
    /api/v1/workspaces/{workspace_id}/members

    List members Returns Page_MemberOut_.

    workspace_id path, required
    string (uuid)
    limit query
    integer Items per page.
    cursor query
    string | null From a previous page's next_cursor.
  • PATCH
    /api/v1/workspaces/{workspace_id}/members/{user_id}

    Change a member's role Returns MemberOut.

    user_id path, required
    string
    workspace_id path, required
    string (uuid)
  • DELETE
    /api/v1/workspaces/{workspace_id}/members/{user_id}

    Remove a member, or leave

    user_id path, required
    string
    workspace_id path, required
    string (uuid)