Endpoints

The Nubo Public API is read-only. It exposes projects, usage aggregates, session metadata, your plan and your remaining allowance. Every endpoint is a GET.

All paths below are relative to the base URL, and every request authenticates with the X-API-Key header. See Authentication for how to create and manage keys.

Base URL

https://api.nubo-chat.com

Read-only API

All public API endpoints use GET. The API does not create projects, send chat messages, or modify workspace settings.

Parameter	Type	Required	Description
projectId	string	No	Restrict results to one project. Omit to span the workspace.

The workspace's original project may have an id equal to the workspace id for historical reasons. Do not treat the two as interchangeable — projects created later have unrelated ids. Always read project ids from this endpoint.

Possible errors:401429See Errors

cURL

curl https://api.nubo-chat.com/v1/projects \
  -H "X-API-Key: YOUR_API_KEY"

200 OK

[
  {
    "id": "8f14e45f-ceea-467a-9ae4-2c1e2f0f1a3b",
    "name": "Support Bot",
    "isActive": true,
    "createdAt": "2026-03-11T09:22:41Z",
    "isDefault": true
  },
  {
    "id": "c2b7d914-5f30-4a1e-9d62-7be0e4c1a558",
    "name": "Docs Assistant",
    "isActive": true,
    "createdAt": "2026-05-02T14:05:09Z",
    "isDefault": false
  }
]

Get project

GET/v1/projects/{projectId}

Returns a single project by id.

Path parameters

Parameter	Type	Required	Description
projectId	string	Yes	The id of the project to retrieve.

Possible errors:404 project_not_found401429See Errors

cURL

curl https://api.nubo-chat.com/v1/projects/PROJECT_ID \
  -H "X-API-Key: YOUR_API_KEY"

200 OK

{
  "id": "8f14e45f-ceea-467a-9ae4-2c1e2f0f1a3b",
  "name": "Support Bot",
  "isActive": true,
  "createdAt": "2026-03-11T09:22:41Z",
  "isDefault": true
}

404 project_not_found

{
  "error": {
    "code": "project_not_found",
    "message": "No project with that id exists for this API key.",
    "traceId": "0HN7A2QK9V1M4:00000004"
  }
}

Usage

Aggregated usage and performance metrics for conversations handled by Nubo. All three endpoints accept optional project scoping.

Usage summary

GET/v1/usage

Headline usage totals over a trailing time window.

Query parameters

Parameter	Type	Required	Default	Description
days	integer	No	30	Trailing reporting window in days. Accepted range `1`–`365`; a value outside it is rejected with `invalid_request`.
projectId	string	No	—	Restrict results to one project. Omit to span the workspace.

Possible errors:401429See Errors

cURL

curl "https://api.nubo-chat.com/v1/usage?days=30" \
  -H "X-API-Key: YOUR_API_KEY"

Scoped to one project

curl "https://api.nubo-chat.com/v1/usage?days=30&projectId=PROJECT_ID" \
  -H "X-API-Key: YOUR_API_KEY"

200 OK

{
  "rangeDays": 30,
  "totalConversations": 412,
  "totalMessages": 1187,
  "totalTokens": 2043911,
  "promptTokens": 1402388,
  "completionTokens": 641523,
  "avgResponseMs": 1840,
  "rerankingRate": 68.4,
  "toolCalls": 233
}

Usage series

GET/v1/usage/series

Returns one usage point per UTC day across the window.

Query parameters

Parameter	Type	Required	Default	Description
days	integer	No	30	Trailing reporting window in days. Accepted range `1`–`365`; a value outside it is rejected with `invalid_request`.
projectId	string	No	—	Restrict results to one project. Omit to span the workspace.

Missing days

Days with no activity are omitted from the response rather than returned with zero values. If your UI requires a continuous daily series, fill those gaps client-side.

Possible errors:401429See Errors

cURL

curl "https://api.nubo-chat.com/v1/usage/series?days=30" \
  -H "X-API-Key: YOUR_API_KEY"

200 OK

[
  {
    "date": "2026-08-06T00:00:00Z",
    "messages": 41,
    "conversations": 15,
    "tokens": 71204
  },
  {
    "date": "2026-08-07T00:00:00Z",
    "messages": 58,
    "conversations": 22,
    "tokens": 99871
  },
  {
    "date": "2026-08-09T00:00:00Z",
    "messages": 33,
    "conversations": 12,
    "tokens": 58440
  }
]

Usage by model

GET/v1/usage/models

Returns usage grouped by the model that generated each reply, busiest model first.

Query parameters

Parameter	Type	Required	Default	Description
days	integer	No	30	Trailing reporting window in days. Accepted range `1`–`365`; a value outside it is rejected with `invalid_request`.
projectId	string	No	—	Restrict results to one project. Omit to span the workspace.

Possible errors:401429See Errors

cURL

curl "https://api.nubo-chat.com/v1/usage/models?days=30" \
  -H "X-API-Key: YOUR_API_KEY"

200 OK

[
  {
    "modelName": "claude-sonnet-4",
    "provider": "anthropic",
    "messages": 803,
    "tokens": 1402388
  },
  {
    "modelName": "gpt-4o-mini",
    "provider": "openai",
    "messages": 384,
    "tokens": 641523
  }
]

Sessions

Sessions are conversations reconstructed from recorded turns.

Metadata only

Nubo does not persist message text through this API. Session endpoints return conversation metadata — timings, token counts, models and tool calls — never chat transcripts.

List sessions

GET/v1/sessions

Returns a paginated list of sessions, ordered by most recent activity first.

Query parameters

Parameter	Type	Required	Default	Description
from	ISO 8601 datetime	No	—	Inclusive lower bound on activity time, in UTC.
to	ISO 8601 datetime	No	—	Inclusive upper bound on activity time, in UTC.
page	integer	No	1	1-based page number.
pageSize	integer	No	25	Rows per page. Maximum 100.
projectId	string	No	—	Restrict results to one project. Omit to span the workspace.

Polling sessions

New activity can move older rows onto later pages. When paging through a live list, this can cause records to be skipped.

For stable pagination during polling, set both from and to, then page through that fixed time window.

Possible errors:401429See Errors

cURL

curl "https://api.nubo-chat.com/v1/sessions?page=1&pageSize=25" \
  -H "X-API-Key: YOUR_API_KEY"

Bounded polling window

curl "https://api.nubo-chat.com/v1/sessions\
?from=2026-08-10T09%3A00%3A00Z\
&to=2026-08-10T10%3A00%3A00Z\
&page=1&pageSize=25" \
  -H "X-API-Key: YOUR_API_KEY"

200 OK

{
  "items": [
    {
      "sessionId": "sess_01J9YQ2M7K4T8XN3P5RB6VW0AZ",
      "startedAt": "2026-08-10T09:14:02Z",
      "lastActivityAt": "2026-08-10T09:21:47Z",
      "messages": 6,
      "totalTokens": 9871,
      "avgResponseMs": 1720,
      "toolCalls": 2,
      "rerankingRate": 66.7,
      "models": [
        "claude-sonnet-4"
      ]
    }
  ],
  "total": 47,
  "page": 1,
  "pageSize": 25
}

Get session

GET/v1/sessions/{sessionId}

Returns totals for a single conversation together with metadata for each recorded turn, oldest first.

Path parameters

Parameter	Type	Required	Description
sessionId	string	Yes	The session id to retrieve.

Query parameters

Parameter	Type	Required	Description
projectId	string	No	Restrict the lookup to one project.

Possible errors:404 session_not_found401429See Errors

cURL

curl https://api.nubo-chat.com/v1/sessions/SESSION_ID \
  -H "X-API-Key: YOUR_API_KEY"

200 OK

{
  "sessionId": "sess_01J9YQ2M7K4T8XN3P5RB6VW0AZ",
  "startedAt": "2026-08-10T09:14:02Z",
  "lastActivityAt": "2026-08-10T09:21:47Z",
  "messages": 2,
  "totalTokens": 3310,
  "avgResponseMs": 1755,
  "toolCalls": 1,
  "rerankingRate": 50.0,
  "models": [
    "claude-sonnet-4"
  ],
  "turns": [
    {
      "timestamp": "2026-08-10T09:14:02Z",
      "modelName": "claude-sonnet-4",
      "provider": "anthropic",
      "promptTokens": 1180,
      "completionTokens": 402,
      "totalTokens": 1582,
      "durationMs": 1610,
      "toolCalls": 0,
      "rerankingApplied": true
    },
    {
      "timestamp": "2026-08-10T09:21:47Z",
      "modelName": "claude-sonnet-4",
      "provider": "anthropic",
      "promptTokens": 1290,
      "completionTokens": 438,
      "totalTokens": 1728,
      "durationMs": 1900,
      "toolCalls": 1,
      "rerankingApplied": false
    }
  ]
}

404 session_not_found

{
  "error": {
    "code": "session_not_found",
    "message": "No session with that id exists for this API key.",
    "traceId": "0HN7A2QK9V1M4:00000006"
  }
}

Account

Workspace-level plan and allowance information.

Workspace-level

Neither endpoint in this group accepts projectId. The allowance and the plan belong to the workspace, not to any one project.

Balance

GET/v1/balance

Returns the number of replies included, used and remaining in the current allowance period.

Do not calculate the billing period yourself

Use periodStart and periodEnd exactly as returned. The meaning of the period is given by periodBasis, which reads calendar_month today and becomes subscription_period once subscription billing periods are in use.

Do not assume a period always begins on the first day of a month.

Possible errors:401429See Errors

cURL

curl https://api.nubo-chat.com/v1/balance \
  -H "X-API-Key: YOUR_API_KEY"

200 OK

{
  "planKey": "pro",
  "included": 10000,
  "used": 3421,
  "remaining": 6579,
  "periodStart": "2026-08-01T00:00:00Z",
  "periodEnd": "2026-09-01T00:00:00Z",
  "periodBasis": "calendar_month"
}

Plan

GET/v1/plan

Returns the workspace's assigned plan and its current entitlements. Entitlements only — no pricing, billing history, payment details or invoices.

Possible errors:401429See Errors

cURL

curl https://api.nubo-chat.com/v1/plan \
  -H "X-API-Key: YOUR_API_KEY"

200 OK

{
  "planKey": "pro",
  "name": "Pro",
  "description": "For teams running production assistants.",
  "entitlements": {
    "schemaVersion": 1,
    "replyAllowance": {
      "included": 10000,
      "period": "month",
      "overage": "block"
    },
    "rateLimits": {
      "requestsPerMinute": 60,
      "maxConcurrent": 8
    },
    "models": {
      "allowed": [
        "*"
      ],
      "autoSelect": true
    },
    "features": {
      "reranking": true,
      "mcpTools": true,
      "maxToolInvocations": 8,
      "removeBranding": true
    },
    "knowledge": {
      "maxSources": 200
    },
    "projects": {
      "max": 5
    }
  }
}

Endpoints

Projects

List projects

Query parameters

Get project

Path parameters

Usage

Usage summary

Query parameters

Usage series

Query parameters

Usage by model

Query parameters

Sessions

List sessions

Query parameters

Get session

Path parameters

Query parameters

Account

Balance

Plan