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.
- In your project, click Settings, and then Service accounts.
- Click New service account.
- Enter a name, such as
Docs tutorial. kosem fills in the Account ID from it. - Under Role in this project, select Viewer.
- Click Create service account.
2. Create an API key
- On the service account's page, click Create API key, and then Create API key in the dialog.
- Copy the key, which starts with
kosem_sk_. kosem shows it only once. - 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
- Click Settings, and then General.
- 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
- Read the API conventions: resource names, pages and errors.
- Browse the API reference.
- Learn how roles and service accounts work.