DocsAPI Reference
Open API console

Endpoints

The Nubo Public API is read-only. It exposes projects, usage aggregates, session metadata, evaluation sets and their results, 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.

Projects

Projects are the agents owned by the workspace associated with the API key.

List projects

GET/v1/projects

Returns the projects belonging to the workspace associated with the API key.

Query parameters

ParameterTypeRequiredDescription
projectIdstringNoRestrict results to one project. Omit to span the workspace.

Project ids are not workspace ids

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

ParameterTypeRequiredDescription
projectIdstringYesThe 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

ParameterTypeRequiredDefaultDescription
daysintegerNo30Trailing reporting window in days. Accepted range 1–365; a value outside it is rejected with invalid_request.
projectIdstringNo—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

ParameterTypeRequiredDefaultDescription
daysintegerNo30Trailing reporting window in days. Accepted range 1–365; a value outside it is rejected with invalid_request.
projectIdstringNo—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

ParameterTypeRequiredDefaultDescription
daysintegerNo30Trailing reporting window in days. Accepted range 1–365; a value outside it is rejected with invalid_request.
projectIdstringNo—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

ParameterTypeRequiredDefaultDescription
fromISO 8601 datetimeNo—Inclusive lower bound on activity time, in UTC.
toISO 8601 datetimeNo—Inclusive upper bound on activity time, in UTC.
pageintegerNo11-based page number.
pageSizeintegerNo25Rows per page. Maximum 100.
projectIdstringNo—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

ParameterTypeRequiredDescription
sessionIdstringYesThe session id to retrieve.

Query parameters

ParameterTypeRequiredDescription
projectIdstringNoRestrict 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"
  }
}

Evaluation

Each project's evaluation set, its settings, and the runs that score the agent against it. Sets are edited and runs are started in the Nubo portal; see the Evaluation guide for what each score means.

List evaluation sets

GET/v1/evaluation/sets

Returns each project's evaluation set with its questions and settings — the pass threshold, the recurring schedule and the threshold alert. A project has at most one set.

Query parameters

ParameterTypeRequiredDescription
projectIdstringNoReturn only this project's set. Omit to list every project that has one.

A project may have no set yet

A set is created the first time someone opens the Evaluation page for a project. Until then the project is absent from this list — with projectId you get an empty array, not a 404. schedule and alert are null until they are first saved.

Alert recipients are not exposed

The alert reports its thresholds and which metrics are currently breached, but not who it emails. Recipients are managed in the portal only.

Possible errors:401429See Errors

cURL
curl "https://api.nubo-chat.com/v1/evaluation/sets?projectId=PROJECT_ID" \
  -H "X-API-Key: YOUR_API_KEY"
200 OK
[
  {
    "id": "5b0c2f4e-8a1d-4c3e-9f27-1d6e4a7b9c02",
    "projectId": "8f14e45f-ceea-467a-9ae4-2c1e2f0f1a3b",
    "name": "Support Bot",
    "description": null,
    "createdAt": "2026-08-12T10:04:11Z",
    "updatedAt": "2026-09-30T08:41:56Z",
    "settings": {
      "passThreshold": 4,
      "schedule": {
        "isEnabled": true,
        "daysOfWeek": [1, 4],
        "hourLocal": 9,
        "timeZoneId": "Asia/Jerusalem",
        "nextRunAt": "2026-10-12T06:00:00Z",
        "lastRunAt": "2026-10-08T06:00:41Z",
        "lastSkipReason": null,
        "consecutiveFailures": 0,
        "pausedByPlan": false,
        "stoppedAfterFailures": false
      },
      "alert": {
        "isEnabled": true,
        "thresholds": {
          "passRate": 0.8,
          "faithfulness": 4.0,
          "relevance": null,
          "completeness": null,
          "contextSufficiency": 3.5,
          "sourceHitRate": null
        },
        "breachedMetrics": [],
        "breachedSince": null,
        "lastEvaluatedAt": "2026-10-08T06:07:12Z",
        "lastEvaluatedRunId": "3d9a6c71-2b4e-4f8a-a1c5-7e20b9d84f16"
      }
    },
    "questions": [
      {
        "id": "a4c27d10-6e3b-4b8f-9c51-0f2e8d7a6b34",
        "position": 0,
        "question": "How do I reset my password?",
        "expectedAnswer": "Use Forgot password on the sign-in page; the link expires after 30 minutes.",
        "expectedSources": ["account-help.pdf"],
        "isEnabled": true,
        "source": "authored",
        "notes": null,
        "createdAt": "2026-08-12T10:06:30Z",
        "updatedAt": "2026-08-12T10:06:30Z"
      },
      {
        "id": "f19b3e52-7c04-4d6a-8e21-5a9c0b4d2e87",
        "position": 1,
        "question": "Which payment methods do you accept?",
        "expectedAnswer": null,
        "expectedSources": [],
        "isEnabled": true,
        "source": "generated",
        "notes": null,
        "createdAt": "2026-08-12T10:05:02Z",
        "updatedAt": "2026-08-12T10:05:02Z"
      }
    ]
  }
]

List evaluation runs

GET/v1/evaluation/runs

Returns a paginated list of evaluation runs, newest first, with the configuration each ran under and its scores. Per-question results come from Get evaluation run.

Query parameters

ParameterTypeRequiredDefaultDescription
fromISO 8601 datetimeNo—Inclusive lower bound on when the run was created, in UTC.
toISO 8601 datetimeNo—Inclusive upper bound on when the run was created, in UTC.
statusstringNo—One of queued, running, completed, failed, cancelled.
triggerstringNo—manual or scheduled.
pageintegerNo11-based page number.
pageSizeintegerNo25Rows per page. Maximum 100.
projectIdstringNo—Restrict results to one project. Omit to span the workspace.

Scores arrive when the run finishes

Scores are written once, at the end of a run. Until status is completed, the averages, scoredCount and passRate are null — even when completedCount already equals questionCount.

Only completed runs are comparable over time. To chart a trend, request status=completed and compare the config of neighbouring runs: a changed systemPromptHash, knowledgeFingerprint or modelName is usually what explains a moved score.

Possible errors:401429See Errors

cURL
curl "https://api.nubo-chat.com/v1/evaluation/runs?status=completed&projectId=PROJECT_ID" \
  -H "X-API-Key: YOUR_API_KEY"
200 OK
{
  "items": [
    {
      "id": "3d9a6c71-2b4e-4f8a-a1c5-7e20b9d84f16",
      "projectId": "8f14e45f-ceea-467a-9ae4-2c1e2f0f1a3b",
      "evaluationSetId": "5b0c2f4e-8a1d-4c3e-9f27-1d6e4a7b9c02",
      "status": "completed",
      "cancelReason": null,
      "label": "Support Bot",
      "trigger": "scheduled",
      "createdAt": "2026-10-08T06:00:41Z",
      "startedAt": "2026-10-08T06:00:58Z",
      "completedAt": "2026-10-08T06:07:12Z",
      "questionCount": 10,
      "completedCount": 10,
      "failedCount": 0,
      "config": {
        "modelName": "claude-sonnet-4",
        "provider": "anthropic",
        "temperature": 0.3,
        "rerankingEnabled": true,
        "topK": 5,
        "systemPromptHash": "cf07194ee232eb531e15f690000d19846dea69cf05504782658afcfacb9228a2",
        "knowledgeFingerprint": "74fec0c33e96ab90ac88666979207a50a6ea7b9b3eea6ec0e8b916d64c0a0706"
      },
      "avgContextSufficiency": 4.4,
      "avgFaithfulness": 4.7,
      "avgRelevance": 4.6,
      "avgCompleteness": 4.1,
      "groundedRate": 0.9,
      "sourceHitRate": 0.8,
      "scoredCount": 10,
      "passedCount": 8,
      "passRate": 0.8,
      "judgeFailureCount": 0,
      "simulatedToolCallRate": 0.1,
      "totalPromptTokens": 48210,
      "totalCompletionTokens": 6934
    }
  ],
  "total": 14,
  "page": 1,
  "pageSize": 25
}

Get evaluation run

GET/v1/evaluation/runs/{runId}

Returns one run together with the outcome of each question: the question as asked, the agent's answer, the four judge scores, what retrieval returned and which tools the model asked for.

Path parameters

ParameterTypeRequiredDescription
runIdstringYesThe id of the run to retrieve.

Query parameters

ParameterTypeRequiredDescription
projectIdstringNoRestrict the lookup to one project.

A score of 0 means not scored

Judge scores run from 1 to 5. A 0 means the result was not scored — status is failed, or judgeError says why the judge could not score it. Never treat it as a bad answer.

Tools never run during an evaluation

simulatedToolCalls lists the tools the model asked for. None of them were called, so an answer that needed live data was written without it.

Older runs may have no results

Your plan sets how many runs keep their per-question detail. An older run still returns its scores, with an empty results array.

Possible errors:404 evaluation_run_not_found401429See Errors

cURL
curl https://api.nubo-chat.com/v1/evaluation/runs/RUN_ID \
  -H "X-API-Key: YOUR_API_KEY"
200 OK
{
  "run": {
    "id": "3d9a6c71-2b4e-4f8a-a1c5-7e20b9d84f16",
    "projectId": "8f14e45f-ceea-467a-9ae4-2c1e2f0f1a3b",
    "evaluationSetId": "5b0c2f4e-8a1d-4c3e-9f27-1d6e4a7b9c02",
    "status": "completed",
    "cancelReason": null,
    "label": "Support Bot",
    "trigger": "scheduled",
    "createdAt": "2026-10-08T06:00:41Z",
    "startedAt": "2026-10-08T06:00:58Z",
    "completedAt": "2026-10-08T06:07:12Z",
    "questionCount": 10,
    "completedCount": 10,
    "failedCount": 0,
    "config": {
      "modelName": "claude-sonnet-4",
      "provider": "anthropic",
      "temperature": 0.3,
      "rerankingEnabled": true,
      "topK": 5,
      "systemPromptHash": "cf07194ee232eb531e15f690000d19846dea69cf05504782658afcfacb9228a2",
      "knowledgeFingerprint": "74fec0c33e96ab90ac88666979207a50a6ea7b9b3eea6ec0e8b916d64c0a0706"
    },
    "avgContextSufficiency": 4.4,
    "avgFaithfulness": 4.7,
    "avgRelevance": 4.6,
    "avgCompleteness": 4.1,
    "groundedRate": 0.9,
    "sourceHitRate": 0.8,
    "scoredCount": 10,
    "passedCount": 8,
    "passRate": 0.8,
    "judgeFailureCount": 0,
    "simulatedToolCallRate": 0.1,
    "totalPromptTokens": 48210,
    "totalCompletionTokens": 6934
  },
  "results": [
    {
      "id": "e71f0b2a-93c6-4d5e-b8a4-2f61c7d09e53",
      "questionId": "a4c27d10-6e3b-4b8f-9c51-0f2e8d7a6b34",
      "question": "How do I reset my password?",
      "expectedAnswer": "Use Forgot password on the sign-in page; the link expires after 30 minutes.",
      "expectedSources": ["account-help.pdf"],
      "answer": "Select Forgot password on the sign-in page and follow the link we email you. The link is valid for 30 minutes.",
      "modelUsed": "claude-sonnet-4",
      "status": "ok",
      "contextSufficiency": 5,
      "faithfulness": 5,
      "relevance": 5,
      "completeness": 4,
      "isGrounded": true,
      "passed": true,
      "unsupportedClaims": [],
      "judgeNotes": "Matches the help article. Does not mention that a new link can be requested.",
      "judgeError": null,
      "sourceHit": true,
      "retrievedChunks": [
        {
          "source": "account-help.pdf",
          "position": 3,
          "score": 0.82,
          "rerankScore": 0.97,
          "excerpt": "Forgot your password? On the sign-in page, select Forgot password and enter the email address on your account…"
        }
      ],
      "simulatedToolCalls": [],
      "timings": {
        "embedMs": 112,
        "retrieveMs": 64,
        "rerankMs": 380,
        "generateMs": 2140,
        "judgeMs": 3015
      },
      "promptTokens": 4120,
      "completionTokens": 612,
      "createdAt": "2026-10-08T06:01:09Z"
    }
  ]
}
404 evaluation_run_not_found
{
  "error": {
    "code": "evaluation_run_not_found",
    "message": "No evaluation run with that id exists for this API key.",
    "traceId": "0HN7A2QK9V1M4:00000009"
  }
}

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,
      "allowedModels": []
    },
    "features": {
      "reranking": true,
      "mcpTools": true,
      "maxToolInvocations": 8,
      "removeBranding": true
    },
    "knowledge": {
      "maxSources": 200
    },
    "projects": {
      "max": 5
    }
  }
}