Make your first call¶

Send a request to a language model with your Core API key, then check the response and your key's permissions. You need your deployment's API address and an available model id.

Get an API key¶

Ask your administrator for an API key, the Core address and the model ids you can use. The administrator creates the key in the console. Its secret has this format:

ack_Zr7mQ1x9t0LpB3vK8sN2wY6cH4dF5gJ

Core displays the secret only when the key is created. Store it with your other credentials. If it is exposed, ask your administrator to rotate it. Rotation disables the old secret immediately and preserves the key's id and history.

Set these environment variables for the examples in this guide:

export CORE_URL=https://core.example.com/api/v1
export CORE_KEY='ack_...'

Replace https://core.example.com with your installation address and ack_... with your secret.

Send a request¶

Replace <a model id> with a model available to your organisation:

curl -s -X POST "$CORE_URL/responses" \
    -H "Authorization: Bearer $CORE_KEY" \
    -H "Content-Type: application/json" \
    -d '{"model": "<a model id>", "input": "Give me three names for a coffee shop."}'

Pass the API key secret directly as the bearer token. You do not need to sign in or exchange it for another token.

Read the response¶

The response contains the model's output and token usage:

{
  "id": "resp_0KQ2mR...",
  "object": "response",
  "status": "completed",
  "model": "<a model id>",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [{ "type": "output_text", "text": "Bean There, Daily Grind, Roast & Toast" }]
    }
  ],
  "usage": { "input_tokens": 14, "output_tokens": 12, "total_tokens": 26 }
}

Check status before using the output:

These statuses can arrive with HTTP 200 or 201. The HTTP code tells you whether Core accepted and stored the request; status tells you how the turn ended.

Save the X-Request-Id response header when logging a request or reporting a problem. It identifies the corresponding records in Core.

Check your capabilities¶

curl -s "$CORE_URL/key" -H "Authorization: Bearer $CORE_KEY"

GET /key returns the key's organisation, currently enabled capabilities and policy. The policy is a list of rules and a few settings. Each rule permits or forbids one kind of thing: a model, a tool, a host a tool may contact, a prompt, a skill, a file, a thread. A key reaches something when a permit matches it and no forbid does. The example shows two of the rules a key registered without a policy of its own carries; the full list and what each part means are in Write your first rule.

{
  "id": "key_7Hn2...",
  "tenant_id": "ten_4Kd9...",
  "secret_prefix": "ack_Zr7mQ1x9",
  "name": "Checkout service",
  "capabilities": { "threads": {}, "files": { "max_bytes": 10485760 } },
  "policy": {
    "rules": [
      { "id": "model", "effect": "permit", "kind": "model",
        "match": { "names": null, "labels": {} }, "when": [] },
      { "id": "thread-own", "effect": "permit", "kind": "thread",
        "match": { "names": null, "labels": {} },
        "when": [{ "atom": "label_is_subject", "label": "subject" }] }
    ],
    "settings": {
      "subjects_required": false,
      "agents_required": false,
      "writable_labels": {},
      "regions_allow": null,
      "region_exceptions": [],
      "host_regions": {}
    }
  }
}

Permissions can change after a key is created. Use this endpoint to check the current settings.

Troubleshoot a 404¶

A 404 means the resource is unavailable to your key. It may not exist, may belong to another organisation, or may require a capability that is disabled.

Check GET /key first. Ask your administrator to enable a missing capability. If it is already enabled, check the resource id and organisation. Core uses the same status for these cases to avoid exposing another organisation's resources.

Next steps¶