AGENTS.md

Start here

Use this page to choose the correct Callabo API resource and workflow. Use the locale-specific OpenAPI document as the source of truth for exact paths, parameters, schemas, and examples.

AI workflow

1. 1

   Read this quick reference

   Identify the resource, authentication model, and guardrails before generating code.

2. 2

   Select the API operation

   Route the request to Workspaces, Records, Teams, Members, Labels, or Roles.

3. 3

   Read the matching OpenAPI operation

   Copy its path, parameters, response schema, and example without inventing fields.

4. 4

   Generate direct HTTP code

   Keep the PAT on the server and handle the documented response and error types.

Critical guardrails

• Use only endpoints published in OpenAPI. Do not generate undocumented endpoints.
• Authenticate with Authorization: Bearer <PAT> and never place the PAT in a URL, browser bundle, source code, or log.
• A PAT belongs to one person. It has no separate scope layer and uses the owner's current workspace and team permissions at request time.
• A workspace list can include a workspace where PAT access is disabled. Do not assume a listed slug supports workspace-scoped operations.
• A PAT-disabled workspace responds with HTTP 401 and exactly {"type":"UNAUTHORIZED"}, with no data or reason; it is indistinguishable from an expired or revoked PAT.
• Use each operation's documented HTTP method. Run write operations only with explicit user intent.
• Official SDKs are not available. Language examples use direct HTTP libraries; treat generated or community SDKs as unofficial.
• Use OpenAPI as the source of truth. Do not infer request fields, response fields, enum values, or nullability from examples alone.

Request contract

• Base URL: https://api.callabo.ai.
• Authentication header: Authorization: Bearer $CALLABO_PAT.
• Korean OpenAPI: /v2/openapi.ko.json.
• English OpenAPI: /v2/openapi.en.json.
• Japanese OpenAPI: /v2/openapi.ja.json.
• The OpenAPI locale is selected by its URI. Do not use Accept-Language to select it.

Resource routing

Main usage flow

Common mistakes

• Do not assume a PAT keeps permissions that its owner has lost.
• Do not assume a workspace returned by GET /v2/workspaces accepts PAT-scoped requests.
• Do not treat nullable response fields as required values.
• Do not reuse a pagination cursor with changed filters or sort order.
• Do not treat the original media endpoint as a transcript endpoint.
• Do not invent write operations or SDK methods that are absent from OpenAPI.

Reference routing