Skip to Content
kosemdocs
Reference

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.ai

Every 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

ResourceName
Organizationorganizations/org_…
Projectprojects/prj_…
In a projectprojects/prj_…/agents/ags_…
In an organization or a projectorganizations/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

MethodHTTPExample
ListGET on a collectionGET /v1/projects/{project}/agents
GetGET on a resourceGET /v1/projects/{project}
CreatePOST on a collectionPOST /v1/projects
UpdatePATCH on a resourcePATCH /v1/projects/{project}
DeleteDELETE on a resourceDELETE /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.

FieldInMeaning
pageSizeQueryHow many to return. Each list method says its default and maximum.
pageTokenQueryThe nextPageToken of the previous page.
nextPageTokenResponseThe 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": "…" }
}
FieldAlwaysMeaning
statusYesThe HTTP status.
codeYesWhat went wrong, from the codes below.
detailNoWhat went wrong, for people. It can change: don't match on it.
reasonNoWhy, for programs to tell failures apart by, such as CREDITS_EXHAUSTED.
domainNoThe service the reason belongs to, such as billing.kosem.ai.
metadataNoWhat the reason concerns, such as the quota that was exceeded.
errorsNoThe parts of the request that are invalid.
retryAfterNoThe 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

CodeHTTPMeaning
invalid_argument400The request is invalid. errors says which parts.
failed_precondition400The request is valid, but the resource isn't in a state to allow it.
out_of_range400A value is past the range the operation takes.
unauthenticated401The request has no valid credentials.
permission_denied403The caller doesn't have permission, or the resource doesn't exist.
not_found404The resource doesn't exist.
already_exists409A resource with that name or alias already exists.
aborted409The request conflicted with another change. Read again and retry.
resource_exhausted429A quota, a rate limit or the organization's credits ran out.
canceled499The caller canceled the request.
internal500kosem failed. Retry later.
unknown500kosem failed for a reason it doesn't know.
data_loss500Data was lost or corrupted.
unimplemented501The operation isn't available.
unavailable503kosem is unavailable for a moment. Retry later.
deadline_exceeded504The 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.

On this page