Skip to Content
kosemdocs
Get started

Call the API

Create a service account and an API key, then make your first request to kosem's API with curl.

In this tutorial, you give a script an identity of its own on kosem, a service account, and call the API with its key. It takes about 5 minutes.

Before you start

You need:

  • A project that you're an Owner of. The Quickstart creates one.
  • curl, in a terminal.

1. Create a service account

A service account is an identity for software. Its roles decide what its API keys can do.

  1. In your project, click Settings, and then Service accounts.
  2. Click New service account.
  3. Enter a name, such as Docs tutorial. kosem fills in the Account ID from it.
  4. Under Role in this project, select Viewer.
  5. Click Create service account.

2. Create an API key

  1. On the service account's page, click Create API key, and then Create API key in the dialog.
  2. Copy the key, which starts with kosem_sk_. kosem shows it only once.
  3. Click I copied the key.

Anyone with the key can act as the service account, so keep it out of source code. Keys expire after 90 days by default.

In your terminal, keep the key in a variable:

export KOSEM_API_KEY='kosem_sk_…'

3. Find your project's ID

  1. Click Settings, and then General.
  2. Copy the project's ID, such as prj_01m5r9dh9mf0ps98ktkap3562c.
export KOSEM_PROJECT='prj_01m5r9dh9mf0ps98ktkap3562c'

4. Get your project

curl -s "https://api.kosem.ai/v1/projects/$KOSEM_PROJECT" \
  -H "Authorization: Bearer $KOSEM_API_KEY"

kosem answers with the project:

{
  "name": "projects/prj_01m5r9dh9mf0ps98ktkap3562c",
  "parent": "organizations/org_01m5r8w2k3e9vbt6g0d4x7qz1h",
  "slug": "playground",
  "displayName": "Playground",
  "state": "ACTIVE",
  "createTime": "2026-11-12T09:30:00Z",
  "updateTime": "2026-11-12T09:30:00Z"
}

5. Try something the key can't do

The service account is a Viewer, so it can read the project but not change it. Try to rename the project:

curl -s -X PATCH "https://api.kosem.ai/v1/projects/$KOSEM_PROJECT" \
  -H "Authorization: Bearer $KOSEM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"displayName": "Renamed"}'

kosem refuses with a 403 and a problem document that says why:

{
  "status": 403,
  "code": "permission_denied",
  "detail": "…"
}

Every error has this shape. API conventions lists the codes and how to tell failures apart.

6. Clean up

On the service account's page, click Delete, and then Delete service account. Its keys stop working at once.

What you did

  • Created a service account with the Viewer role on your project.
  • Called the API with its key, and saw what a refusal looks like.

Next steps

On this page