API conventions
The rules every call to kosem's API follows, including its base URL, authentication, resource names, pages, errors and retries.
Every operation in the API reference follows these conventions.
Base URL
https://api.kosem.aiEvery path starts with /v1/. Requests and responses are JSON.
Authentication
Send an API key as a bearer token:
Authorization: Bearer kosem_sk_…API keys belong to service accounts. Call the API shows how to create one. A request without valid credentials fails with unauthenticated (401).
Resource names
| Resource | Name |
|---|---|
| Organization | organizations/org_… |
| Project | projects/prj_… |
| In a project | projects/prj_…/agents/ags_… |
| In an organization or a project | organizations/org_…/secrets/sec_… or projects/prj_…/secrets/sec_… |
Paths take IDs, never slugs. GET /v1/organizations/lookup and GET /v1/projects/lookup find an ID from a slug. Organizations and projects explains the names.
Standard methods
| Method | HTTP | Example |
|---|---|---|
| List | GET on a collection | GET /v1/projects/{project}/agents |
| Get | GET on a resource | GET /v1/projects/{project} |
| Create | POST on a collection | POST /v1/projects |
| Update | PATCH on a resource | PATCH /v1/projects/{project} |
| Delete | DELETE on a resource | DELETE /v1/projects/{project}/sites/{site} |
Other actions have paths of their own, such as /v1/projects/{project}/iam-policy.
Pages
List methods return one page at a time.
| Field | In | Meaning |
|---|---|---|
pageSize | Query | How many to return. Each list method says its default and maximum. |
pageToken | Query | The nextPageToken of the previous page. |
nextPageToken | Response | The token for the next page. It's empty on the last page. |
Lists return only what the caller can see.
Lists across projects
To list across an organization's projects, write - for the project and filter by the organization:
export KOSEM_API_KEY='kosem_sk_…'
export KOSEM_ORG='org_01m5r8w2k3e9vbt6g0d4x7qz1h'
curl -s -G "https://api.kosem.ai/v1/projects/-/serviceAccounts" \
-H "Authorization: Bearer $KOSEM_API_KEY" \
--data-urlencode "filter=organization = \"organizations/$KOSEM_ORG\""Errors
A failed call answers with an HTTP status and a problem document, as RFC 9457 defines it, of type application/problem+json:
{
"status": 429,
"code": "resource_exhausted",
"detail": "…",
"domain": "billing.kosem.ai",
"reason": "CREDITS_EXHAUSTED",
"metadata": { "sku": "…" }
}| Field | Always | Meaning |
|---|---|---|
status | Yes | The HTTP status. |
code | Yes | What went wrong, from the codes below. |
detail | No | What went wrong, for people. It can change: don't match on it. |
reason | No | Why, for programs to tell failures apart by, such as CREDITS_EXHAUSTED. |
domain | No | The service the reason belongs to, such as billing.kosem.ai. |
metadata | No | What the reason concerns, such as the quota that was exceeded. |
errors | No | The parts of the request that are invalid. |
retryAfter | No | The seconds to wait before trying again, when kosem knows. |
Match on reason and domain to handle a particular failure. kosem never renames a reason. The API reference lists every reason, with what it means, under the error schema's reason.
Codes
| Code | HTTP | Meaning |
|---|---|---|
invalid_argument | 400 | The request is invalid. errors says which parts. |
failed_precondition | 400 | The request is valid, but the resource isn't in a state to allow it. |
out_of_range | 400 | A value is past the range the operation takes. |
unauthenticated | 401 | The request has no valid credentials. |
permission_denied | 403 | The caller doesn't have permission, or the resource doesn't exist. |
not_found | 404 | The resource doesn't exist. |
already_exists | 409 | A resource with that name or alias already exists. |
aborted | 409 | The request conflicted with another change. Read again and retry. |
resource_exhausted | 429 | A quota, a rate limit or the organization's credits ran out. |
canceled | 499 | The caller canceled the request. |
internal | 500 | kosem failed. Retry later. |
unknown | 500 | kosem failed for a reason it doesn't know. |
data_loss | 500 | Data was lost or corrupted. |
unimplemented | 501 | The operation isn't available. |
unavailable | 503 | kosem is unavailable for a moment. Retry later. |
deadline_exceeded | 504 | The request took too long. |
kosem answers permission_denied for a resource you can't see whether or not it exists, so that nobody learns what exists by asking.
Retries
When kosem knows when a request can succeed, such as after a rate limit, it says so in seconds in the Retry-After header and in the problem's retryAfter. Wait at least that long before trying again.
Access policies
Resources that have their own access policy, such as projects, have an iam-policy path. A policy you read has an etag: send it back when you set the policy, and kosem refuses the change if someone changed the policy in the meantime.
Streams
Some operations stream server-sent events, such as following an agent while it works. A stream that fails after it started ends with an error event.