Use the API

3 min read

The API lets you integrate Kujira with your own systems, automations, and agents. You can inspect an organization's status and operate the resources for which you have granted permission.

Before you start

1. Create a service token from the dashboard.
2. Grant only the permissions your integration needs.
3. Send it in every request through the Authorization header.

The token identifies one organization. Retrieve its identifier with an initial request:

curl "https://api.kujira.so/v1/org?page=1&limit=20" \
  -H "Authorization: Bearer $KUJIRA_TOKEN"

The response includes available organizations in data. A service token has only one; use its id in routes containing {org_id}.

{
  "data": [{ "id": 42, "name": "Acme Inc" }],
  "total": 1,
  "page": 1,
  "limit": 20
}

Each token belongs to one organization. It cannot view or operate another one, even if it knows its identifier.

The API evolves

The API is under active development. We can add, change, or remove routes, fields, and permissions as Kujira evolves. Before automating a critical flow, consult the published contract and review changes when updating your integration.

The published contract is the source of truth

The API reference is generated from a synchronized copy of the OpenAPI contract. Each endpoint shows its method, route, input, response, and required permission.

The public contract contains the supported surface for integrations. Internal dashboard routes are not part of it and must not be used as an alternative API.

To import or check the currently published contract, use the current OpenAPI JSON. The documentation OpenAPI JSON is useful for working with the version you are reading or reviewing a pull request.

Compatibility

For a critical integration, validate routes, parameters, and responses against the published contract. Do not depend on fields absent from it or on dashboard implementation details.

• Use operationId values to identify operations in generated clients or integration tests.
• Branch on error code, not message text.
• Keep a copy of the contract you tested against and compare it with the current contract before updating your integration.

Design secure integrations

• Create one token per integration and name it after its purpose.
• Give it the smallest possible scope: an agent that only reads audit data needs audit.view, not full access.
• Store the token in a secret manager, never in code, screenshots, or messages.
• Set an expiry date and allowed-IP list when you can limit the environment from which it connects.
• Treat 403 as missing permission and 404 as a resource outside the token's scope or one that does not exist.

You can revoke a token instantly from Service tokens. Its actions are recorded in the Activity log.

For agents and external tools

A coding agent, automation flow, or external tool can use the same contract. Give it a limited token and describe the task it must solve—for example, checking alerts, reviewing audit data, or maintaining particular agents. The token precisely defines how far it can go, regardless of the software using it.

Endpoint reference

Check each operation's method, parameters, responses, and required permission.

Service tokens

Create, limit, review, and revoke your integration credentials.