Build applications that run StackAI workflows, search knowledge, invoke connected tools, and measure quality. Start with a working request, then use the reference for exact parameters, request bodies, response schemas, and errors.
\nUse the public REST reference for workflow execution, knowledge bases, integration actions, evaluations, skills, and webhook subscriptions. Each operation states its route version and request contract. SCIM uses separate provisioning credentials and protocol responses.
\n| Your goal | \nStart here | \nWhat you need | \n
|---|---|---|
| Run a workflow from your backend | \nQuickstart, then Runs v2 | \nPublished project, personal API key, input keys | \n
| Stream a response to an application | \nLegacy inference and streaming | \nPublished flow, API key, SSE-capable client | \n
| Upload documents and retrieve passages | \nKnowledge ingestion and search | \nKnowledge base access and indexing/query permissions | \n
| Call an integration action | \nProviders and connections | \nExisting connection, action schema, use permission | \n
| Regression-test a workflow | \nEvaluations and monitors | \nProject contract, dataset, evaluator, experiment | \n
| Publish reusable instructions | \nSkills and versions | \nSkill authoring permissions, bundle or form fields | \n
| Receive signed notifications | \nWebhooks | \nAuthorized administrator, HTTPS receiver | \n
| Provision users and groups | \nSCIM provisioning | \nSCIM token and identity-provider configuration | \n
The API version is part of each route. Do not prepend /v2 to a legacy route. The specification's info.version is the document/service version, not a promise that every path has that version. A project version is a third, separate concept: it selects a saved workflow snapshot.
Run a saved workflow from your backend and read its result. This walkthrough uses the same saved project version for the input schema and execution, so a newer unpublished edit cannot change the input contract halfway through.
\nCreate a personal API key in StackAI → Settings → API Keys, in the organization containing your project. Give it projects.read, projects.run, and analytics.read. The key owner must also have access to the project. Store the key in your backend's secret manager.
Publish the project and enable run logging. Copy the project ID from its URL. In the project's version history, select the saved version you intend to run and note its version number. Use that number throughout this walkthrough. Saved versions and API versions are separate: /v2 selects the API contract; PROJECT_VERSION selects workflow content.
export STACKAI_BASE_URL='https://api.stack-ai.com'\nexport PROJECT_ID='YOUR_PROJECT_ID'\nexport PROJECT_VERSION='1' # Replace with your selected saved version number.\n# Set STACKAI_API_KEY through your secret manager or secure local environment.\nFor a private installation, replace the base URL with its configured API origin.
\ncurl --fail-with-body -sS --get \\\n "$STACKAI_BASE_URL/v2/projects/$PROJECT_ID/io-schema" \\\n -H "Authorization: Bearer $STACKAI_API_KEY" \\\n --data-urlencode "version=$PROJECT_VERSION"\nFor a workflow with one text input and one output, a response can look like this:
\n{"data":{"input_kind":"legacy_input_nodes","inputs":[{"id":"in-0","name":"Question"}],"outputs":[{"id":"out-0","name":"Answer"}]}}\nUse the returned id values as object keys, not the display names. Replace in-0 and out-0 below if your project returns different identifiers. latest is useful for discovery, but it can select a different saved version from the published version; this walkthrough pins a number instead.
Create run.json. Replace the project ID and version with the values you selected above:
{"project_id":"YOUR_PROJECT_ID","project_version":1,"input":{"in-0":"Summarize our refund policy"}}\ncurl --fail-with-body -sS -D run-headers.txt \\\n "$STACKAI_BASE_URL/v2/runs" \\\n -H "Authorization: Bearer $STACKAI_API_KEY" \\\n -H 'Content-Type: application/json' \\\n --data-binary @run.json\nA 201 Created response includes a Location header and a run object. Save data.run_id before you do anything else. The status might already have advanced by the time you receive the response. This excerpt shows a run still waiting to execute:
{"data":{"run_id":"5f4c3b2a-1111-4111-8111-123456789abc","project_version":1,"status":"queued","output":null,"error":null}}\nThe excerpt omits timestamps, usage, and other run fields. The endpoint reference contains complete response examples. A 201 confirms creation, not successful execution. If the POST times out, do not automatically repeat it: the first run may already exist.
\nexport RUN_ID='5f4c3b2a-1111-4111-8111-123456789abc' # Use your returned ID.\ncurl --fail-with-body -sS \\\n "$STACKAI_BASE_URL/v2/runs/$RUN_ID" \\\n -H "Authorization: Bearer $STACKAI_API_KEY"\nPoll with a bounded delay. queued and running mean work is in progress. succeeded, failed, and cancelled are terminal. A paused run needs a human response; waiting alone cannot resume it.
A successful response excerpt:
\n{"data":{"run_id":"5f4c3b2a-1111-4111-8111-123456789abc","project_version":1,"status":"succeeded","output":{"out-0":"Eligible purchases can be returned within 30 days."},"error":null}}\nThis text illustrates the response shape; your workflow supplies its own answer. Display the value under the output ID returned in step 2. A failed run can still return HTTP 200 from the status endpoint:
\n{"data":{"run_id":"5f4c3b2a-1111-4111-8111-123456789abc","status":"failed","output":null,"error":"The connected service could not complete the request."}}\nCheck the run's status before displaying its output. Keep its ID so you can inspect the same execution after a process restart. See Run workflows end to end for a bounded polling client and human-input handling.
\nFor the documented REST operations, the portable default is:
\nAuthorization: Bearer YOUR_CREDENTIAL\nA personal API key and a user access token are different credentials even when both use this header. Personal keys begin with sk_. They are tied to an owner and organization, can expire or be revoked, and remain bounded by the owner's live permissions. A JWT is a user session access token governed by the organization's sign-in and MFA rules. Do not use an ID token or refresh token in place of an access token.
| Surface | \nCredential to use | \nImportant distinction | \n
|---|---|---|
| v1 knowledge bases and v2 REST | \nPersonal API key in Bearer; authenticated user JWT where supported | \nResource access and permission checks still apply | \n
/inference/v0/... | \nPersonal API key in Bearer; legacy organization public key where still enabled | \nThese are API-key routes; do not assume a user JWT works | \n
Legacy /analytics/org/... | \nPersonal API key in Bearer; legacy organization private key where still enabled | \nThe legacy public key is not the analytics credential | \n
| SCIM Users and Groups | \nDedicated SCIM token in Bearer | \nNot a normal personal API key or user session token | \n
| Webhook deliveries to your server | \nVerify webhook signature headers | \nThe signing secret is not a StackAI REST API key | \n
Some endpoints accept the raw personal key as X-API-Key: sk_.... Other public routes explicitly read the Bearer authorization header. X-API-Key is not a universal substitute across these APIs. All examples in this documentation use Bearer. Do not send both headers: mixed JWT/key credentials or different keys can be rejected as ambiguous or conflicting. Use the exact Bearer spelling in examples.
| Endpoint family | \nPersonal-key header | \n
|---|---|
/v2/runs and its run detail, resume, and cancel operations | \nAuthorization: Bearer sk_... or X-API-Key: sk_... | \n
/inference/v0/... and legacy /analytics/org/... | \nUse Authorization: Bearer sk_...; do not substitute X-API-Key | \n
| Other REST examples in this guide | \nUse the documented Authorization: Bearer sk_... form | \n
/scim/v2/... | \nUse the dedicated SCIM token in Authorization: Bearer; a personal key is not interchangeable | \n
For example, read a run with the alternative personal-key header:
\ncurl --fail-with-body -sS "$STACKAI_BASE_URL/v2/runs/$RUN_ID" \\\n -H "X-API-Key: $STACKAI_API_KEY"\nObtain personal API keys in StackAI settings. Obtain user access tokens through your organization’s supported sign-in flow. These API routes do not provide a public password-grant login endpoint.
\nA scope grants no extra access beyond the key owner's current permissions. A key can carry kbs.read and still fail to read a knowledge base the owner cannot access. A project can be in the same organization yet unavailable because of folder permissions. Review the permission note on each endpoint.
Typical minimum sets:
\n| Task | \nPermissions/scopes | \n
|---|---|
| Inspect a project's IO | \nprojects.read | \n
| Start/resume/cancel v2 runs | \nprojects.run | \n
| Poll/list v2 runs | \nanalytics.read | \n
| Read a v2 pause token | \nBoth analytics.read and projects.run | \n
| Create, upload, poll, search a KB | \nkbs.create, kbs.index, kbs.read, kbs.query | \n
| Sync a KB | \nkbs.sync | \n
| Browse providers/connections; run action | \nconnections.read; connections.use | \n
| Manage evals | \nRelevant evals.read/create/update/delete/run; trace-backed operations also require analytics.read | \n
| Manage skills | \nRelevant skills.read/create/update/delete | \n
| Manage outbound webhook subscriptions | \norg.webhooks.manage | \n
Webhook management is not an assignable scope in the current personal-key scope picker. Use an authorized user session for this administrative workflow; an existing unscoped key remains subject to its owner's live permissions. Do not widen a production integration's credential just to avoid a scope error.
\nStore keys in a server-side secret manager. Do not embed them in browser JavaScript, mobile binaries, URLs, screenshots, or logs. Put your own authenticated backend between an end-user interface and these APIs. Rotate compromised credentials and update dependent services. An embed-session credential has a restricted surface and is not a general-purpose REST key.
\nUse Content-Type: application/json for JSON bodies. For uploads, use multipart and let the HTTP client generate the boundary. With curl, -F 'file=@document.pdf' is appropriate; do not combine it with a manually set JSON content type. Skill bundles use files (plural), while KB uploads use file (singular).
Encode path segments and query values; never concatenate raw user input into a URL. Repeated array query parameters are sent as repeated keys where the endpoint says so. UUID fields must contain actual UUIDs; a project ID or provider slug is not interchangeable with a run, resource, or connection ID.
\nMost v2 single-resource responses put the object in data. Cursor responses put items in data with next_cursor and potentially other cursor fields. Offset responses include their own pagination metadata. Empty success metadata can be omitted. A 204 has no response body: do not call .json() on it.
Legacy inference, v1 knowledge bases, and legacy analytics do not all share the v2 envelope. Do not add a universal response.data accessor to a client covering every version. Use the exact response schema under each endpoint. v1 KB listing returns an array; v2 KB listing returns an envelope.
| Family | \nPagination | \nTypical default/maximum | \n
|---|---|---|
| v2 runs | \ncursor, page_size | \n50 / 1000 | \n
| KB collections | \ncursor, page_size, direction | \n50 / 1000 | \n
| KB resources | \ncursor, page_size, direction | \n50 / 100 | \n
| Providers, connections, skills, most eval lists, subscriptions | \noffset, limit | \n0 and 50 / 100 | \n
| Eval run scores and sampled runs | \nCursor pagination | \nRead the endpoint's limits | \n
| Legacy analytics | \nZero-based page, page_size | \n0 and 25 | \n
| SCIM | \nOne-based startIndex, count | \nProtocol-specific | \n
Treat cursors as opaque. Keep filters fixed during traversal, URL-encode the cursor, and stop when no next cursor is returned. For offset lists, advance by the items returned and use response totals/has-more information where available. Concurrent changes can affect offset traversals; deduplicate by stable ID if you need a complete export. v1 KB list accepts pagination parameters but returns a bare list without a next-cursor envelope; prefer v2 for new paginated clients rather than inventing a cursor.
\nUse connection/read timeouts, a total deadline, exponential backoff with jitter, and bounded attempts. Retry transient read failures and 429/503 responses when appropriate, honoring Retry-After when present. Stop and fix credentials or permissions for 401/403; fix payloads for 400/422.
Do not automatically retry a run start, action invocation, upload, score creation, or other write after an ambiguous timeout or 500. The operation may already have taken effect, incurred usage, or changed an external system. No general idempotency-key contract is defined here. Persist returned resource IDs, inspect status, and reconcile before deciding to send another write.
\nFor asynchronous operations, preserve Location and any status_url. Resolve relative URLs against the API origin. Only attach credentials to your trusted API origin; a signed file-download URL is a different request and does not need your StackAI authorization header.
Use /v2/runs for persisted asynchronous run creation, list/detail reads, cancellation, and ask-human resume. Use /inference/v0/run/{org_id}/{flow_id} when your integration needs the legacy inline JSON or SSE response contract. These interfaces have different bodies, states, and version selectors.
| Selection | \nv2 run body project_version | \nIO schema query version | \nEval experiment project_version_id | \n
|---|---|---|---|
| Current published | \nOmit or null | \nInspect the known published version number | \nUse the selected saved number | \n
| Draft | \n-1 | \ndraft | \ndraft | \n
| Saved snapshot | \nNonnegative integer | \nNonnegative integer | \nNonnegative integer | \n
| Newest saved | \nNo latest literal | \nlatest (default) | \nNo latest literal | \n
Do not confuse newest saved with published. Draft access is permission-dependent and unsuitable for a reproducible production integration. The legacy inference query uses an integer version: omission or -1 selects the latest published version. In v2, -1 selects the draft instead. Do not copy that value between the two interfaces.
This Python example assumes httpx is installed. It starts exactly one run and never retries the POST automatically. Replace the example input key with the discovered contract.
import os\nimport time\nimport httpx\n\nbase = os.environ.get("STACKAI_BASE_URL", "https://api.stack-ai.com").rstrip("/")\nheaders = {"Authorization": f"Bearer {os.environ['STACKAI_API_KEY']}"}\nwith httpx.Client(base_url=base, headers=headers, timeout=30) as client:\n response = client.post("/v2/runs", json={\n "project_id": os.environ["PROJECT_ID"],\n "input": {"in-0": "Summarize our refund policy"},\n "project_version": int(os.environ["PROJECT_VERSION"]),\n })\n response.raise_for_status()\n run_id = response.json()["data"]["run_id"]\n print("Save this run ID:", run_id)\n deadline = time.monotonic() + 300\n while time.monotonic() < deadline:\n response = client.get(f"/v2/runs/{run_id}")\n response.raise_for_status()\n run = response.json()["data"]\n if run["status"] == "succeeded":\n print(run["output"])\n break\n if run["status"] in {"failed", "cancelled"}:\n raise RuntimeError(f"Run {run_id}: {run['status']}; {run.get('error')}")\n if run["status"] == "paused":\n print("Human input required; retain the run ID and render the prompt securely.")\n break\n time.sleep(2)\n else:\n raise TimeoutError(f"Polling deadline reached; inspect existing run {run_id}")\nA client timeout does not cancel the run. Add bounded retry logic for safe GETs in production. Store the run ID before polling so a process restart can resume observing the same execution.
\nGET the run. When paused, data.pending_input contains the question, expected response type, optional choices, resume token, and token expiry if the caller can both read and resume. A null pending_input does not prove the run has no pause; the caller may lack projects.run.
Submit the actual human answer:
\n{\n "resume_token": "TOKEN_FROM_PENDING_INPUT",\n "response": "THE_HUMAN_ANSWER",\n "response_type": "text"\n}\nPOST this body to /v2/runs/{run_id}/resume, then poll the Location URL. The 202 acknowledges resume acceptance. Match response_type to the prompt (text, approval, or choice); do not invent choices. Keep the token secret, do not log it, and do not reuse it for a later pause. Token expiry is distinct from the pause timeout. Only supported ask-human pauses/backends can be resumed here; 409 means the current state is incompatible.
POST /v2/runs/{run_id}/cancel using the actor type and identity that started the run. Being an administrator or using a session for the same person is not automatically equivalent to the originating personal-key actor. A 404 can conceal inaccessible or non-owned runs. A 202 acknowledges the request; poll until terminal. Cancellation cannot undo side effects already performed by tools.
The legacy inference body is the input map itself, not the v2 {project_id, input} wrapper.
curl --fail-with-body -sS \\\n "$STACKAI_BASE_URL/inference/v0/run/$ORG_ID/$PROJECT_ID" \\\n -H "Authorization: Bearer $STACKAI_API_KEY" \\\n -H 'Content-Type: application/json' \\\n --data '{"in-0":"Summarize our refund policy"}'\nORG_ID must identify the key's organization. The project must be published for this public inference route. Inputs and outputs depend on the deployed flow; use its exported API example or IO contract. Inspect the result state instead of treating every HTTP 200 as completion.
curl --fail-with-body -N -sS \\\n "$STACKAI_BASE_URL/inference/v0/run/$ORG_ID/$PROJECT_ID?delta=false&prefix=true&verbose=true" \\\n -H "Authorization: Bearer $STACKAI_API_KEY" \\\n -H 'Accept: text/event-stream' \\\n -H 'Content-Type: application/json' \\\n --data '{"in-0":"Summarize our refund policy"}'\nParse SSE frames across arbitrary network chunks; a network read is not necessarily an entire JSON event. Inspect the response Content-Type before parsing, because errors may be JSON. Preserve the run identifier when available and handle terminal and paused states. A dropped stream does not prove the run failed. Avoid starting another execution just to reconnect. Disable buffering in your own reverse proxy as needed.
\nFor background legacy execution, pass execution_mode=remote and omit the SSE Accept header. The 202 response supplies a run ID and WebSocket handle; use the returned handle, not a guessed URL. Poll /inference/v0/runs/{org_id}/{run_id} when streaming is unavailable.
For a standard SSE parser, request prefix=true. Request verbose=true to receive the run ID, state, and pause information. With delta=false, each output frame contains the latest complete output values: replace the displayed value rather than appending it. For example:
curl --fail-with-body -N -sS \\\n "$STACKAI_BASE_URL/inference/v0/run/$ORG_ID/$PROJECT_ID?prefix=true&verbose=true&delta=false" \\\n -H "Authorization: Bearer $STACKAI_API_KEY" \\\n -H 'Accept: text/event-stream' \\\n -H 'Content-Type: application/json' \\\n --data '{"in-0":"Summarize our refund policy"}'\nThese illustrative frames show a growing answer followed by the completion marker. Optional progress and citation fields are omitted here:
\ndata: {"outputs":{"out-0":"Eligible purchases"},"run_id":"5f4c3b2a-1111-4111-8111-123456789abc","metadata":{},"state":null}\n\ndata: {"outputs":{"out-0":"Eligible purchases can be returned within 30 days."},"run_id":"5f4c3b2a-1111-4111-8111-123456789abc","metadata":{},"state":"COMPLETED","error":null}\n\ndata: {"outputs":{"type":"stream_complete","message":"Stream completed successfully"},"run_id":"5f4c3b2a-1111-4111-8111-123456789abc","metadata":{"done":true},"state":"COMPLETED","error":null}\nRead state and error, not the marker's message, to decide whether execution succeeded. A completion marker means that the stream ended; its state can also be FAILED, CANCELLED, or PAUSED. Do not display outputs.type or the marker's message as an answer. Save the last answer frame separately. For a pause, preserve pause securely on your backend and obtain the person's response before using the resume endpoint.
The following server-side generator parses frames across arbitrary network chunks. Call it from your application's authenticated backend route. Verify that the signed-in user may run the configured project before calling it; keep the API key and any resume token on the backend.
\nimport json\nimport os\nimport httpx\n\nasync def stream_answer(question, save_run, save_pause):\n base = os.environ["STACKAI_BASE_URL"].rstrip("/")\n path = f"/inference/v0/run/{os.environ['ORG_ID']}/{os.environ['PROJECT_ID']}"\n headers = {"Authorization": f"Bearer {os.environ['STACKAI_API_KEY']}",\n "Accept": "text/event-stream"}\n async with httpx.AsyncClient(base_url=base, timeout=60) as client:\n async with client.stream("POST", path, headers=headers,\n params={"prefix": "true", "verbose": "true", "delta": "false"},\n json={"in-0": question}) as response:\n response.raise_for_status()\n if "text/event-stream" not in response.headers.get("content-type", ""):\n raise RuntimeError("Expected a streaming response")\n data_lines = []\n completed = False\n async for line in response.aiter_lines():\n if line.startswith("data:"):\n data_lines.append(line[5:].lstrip(" "))\n elif line == "" and data_lines:\n event = json.loads("\\n".join(data_lines))\n data_lines = []\n if event.get("run_id"):\n await save_run(event["run_id"])\n if (event.get("metadata") or {}).get("done"):\n completed = True\n yield {"type": "finished", "run_id": event.get("run_id"),\n "state": event.get("state")}\n break\n if event.get("pause"):\n await save_pause(event["run_id"], event["pause"])\n # Keep its resume token out of browser events and logs.\n yield {"type": "needs_input", "run_id": event.get("run_id")}\n elif event.get("state") in {"FAILED", "CANCELLED"}:\n yield {"type": "failed", "run_id": event.get("run_id")}\n elif "out-0" in event.get("outputs", {}):\n yield {"type": "answer", "text": event["outputs"]["out-0"],\n "run_id": event.get("run_id")}\n if not completed:\n raise RuntimeError("Stream disconnected; inspect the saved run ID")\nImplement save_run and save_pause using your application’s durable, access-controlled storage. The output ID and input key above must match your project. Send these normalized events to the browser through your application's own stream. The browser only needs to replace answer text for answer, show a waiting state for needs_input, and check the final state for finished. Render answer text as text, or sanitize any supported rich content; do not inject arbitrary HTML.
If your authenticated backend exposes these normalized events as newline-delimited JSON at /api/answer, a browser client can consume them as follows. The route must authenticate the user, authorize the configured project, call stream_answer, and send one JSON object followed by a newline for each yielded event. Do not pass arbitrary project IDs or API keys through from the browser.
async function showAnswer(question, answerElement, statusElement) {\n const response = await fetch("/api/answer", {\n method: "POST",\n headers: {"Content-Type": "application/json"},\n body: JSON.stringify({question}),\n credentials: "same-origin",\n });\n if (!response.ok || !response.body) throw new Error("Could not start the answer");\n const reader = response.body.pipeThrough(new TextDecoderStream()).getReader();\n let pending = "";\n let finished = false;\n while (true) {\n const {value, done} = await reader.read();\n if (done) break;\n pending += value;\n let boundary;\n while ((boundary = pending.indexOf("\\n")) !== -1) {\n const line = pending.slice(0, boundary);\n pending = pending.slice(boundary + 1);\n if (!line.trim()) continue;\n const event = JSON.parse(line);\n if (event.type === "answer") answerElement.textContent = event.text;\n if (event.type === "needs_input") statusElement.textContent = "Your response is needed";\n if (event.type === "failed") statusElement.textContent = "The request could not finish";\n if (event.type === "finished") {\n finished = true;\n statusElement.textContent = event.state === "COMPLETED" ? "Complete"\n : event.state === "PAUSED" ? "Your response is needed" : "The request did not complete";\n }\n }\n }\n if (!finished) statusElement.textContent = "Connection lost; check this request's saved status";\n}\nA disconnect is not a request to execute again. Retain the run ID and query /inference/v0/runs/{org_id}/{run_id} for its state. This API does not document replay from an SSE Last-Event-ID; do not rely on automatic browser reconnection to resume at the last token.
POST the resume token and human response to /inference/v0/runs/{org_id}/{run_id}/resume. Inline JSON, SSE, and remote resume have different backend support. Trigger-backed runs reject SSE with 406; retry the resume interface without SSE only after checking the response/state, then poll. In-process runs reject execution_mode=remote with 409. An out-of-band response can say RESUMED with no outputs while execution continues. The legacy state vocabulary includes COMPLETED; v2 exposes succeeded.
GET /analytics/org/{org_id}/flows/{flow_id} with a personal key or supported legacy private organization key. It returns a list, using zero-based page and optional page_size, start_date, end_date, user_id, and comma-separated state. Use timezone-qualified timestamps and ensure start is not after end. State values are PENDING, RUNNING, PAUSED, RESUMED, COMPLETED, FAILED, and CANCELLED.
For new run-history integrations, /v2/runs provides cursor pagination and lowercase statuses. A workflow result and a run-history record serve different purposes; logging controls can make run history unavailable.
/v2/knowledge-bases with a name and optional source/indexing configuration. Retain data.knowledge_base_id from the response./v2/knowledge-bases/{knowledge_base_id}/resources as multipart. Retain data.resource_id.data.status is indexed. Treat error as a failure requiring investigation. resource, parsed, and pending are not proof of search readiness; pending_delete and deleted are deletion states./v2/knowledge-bases/{knowledge_base_id}/query and use returned passages and source metadata in your application.curl --fail-with-body -sS "$STACKAI_BASE_URL/v2/knowledge-bases" \\\n -H "Authorization: Bearer $STACKAI_API_KEY" \\\n -H 'Content-Type: application/json' \\\n --data '{"name":"Support handbook","description":"Approved support policies"}'\n\n# Set KB_ID to the returned knowledge_base_id.\ncurl --fail-with-body -sS "$STACKAI_BASE_URL/v2/knowledge-bases/$KB_ID/resources" \\\n -H "Authorization: Bearer $STACKAI_API_KEY" \\\n -F 'file=@handbook.pdf'\n\n# Set RESOURCE_ID to the returned resource_id and poll this URL.\ncurl --fail-with-body -sS "$STACKAI_BASE_URL/v2/knowledge-bases/$KB_ID/resources/$RESOURCE_ID" \\\n -H "Authorization: Bearer $STACKAI_API_KEY"\n\ncurl --fail-with-body -sS "$STACKAI_BASE_URL/v2/knowledge-bases/$KB_ID/query" \\\n -H "Authorization: Bearer $STACKAI_API_KEY" \\\n -H 'Content-Type: application/json' \\\n --data '{"query":"What is the refund window?","top_k":5,"strategy":"hybrid","retrieval_type":"chunks"}'\nUpload automatically starts indexing; a 202 is acceptance, not completion. Bound polling and record the resource ID for recovery. Do not repeatedly upload the same document while waiting. The query endpoint retrieves content; it is not itself a chat/completion endpoint. Empty retrieval is a valid application condition: tell the user there is insufficient evidence rather than fabricate a sourced answer.
\nsemantic searches by meaning, keyword targets lexical matches, and hybrid combines them. top_k is 1–20, default 10. Choose a smaller result set for focused questions; increase only when your downstream context budget supports it. Preserve source attribution. Retrieved text can contain instructions from untrusted documents; treat it as evidence, not system instructions.
Create or update the KB with a valid existing connection_id and source IDs, or supported website sources. Connection/source availability, catalog policy, embedding model access, and KB permissions can all affect admission. Source IDs are provider-specific; do not substitute a display name or an arbitrary URL.
POST /sync for one synchronization and inspect resources afterward. A successful sync request does not mean every resource has been indexed. GET /metadata-schemas to inspect user and dataloader metadata shapes. GET a resource's /download to obtain a signed URL for the original file, and fetch that URL separately without forwarding your API key. Treat signed URLs as temporary secrets.
PATCH updates selected fields; use the schema's nullability rules rather than assuming null means delete. DELETE a resource removes that resource; DELETE the KB removes the KB. Confirm IDs in your own application before destructive actions and check downstream workflows that depend on the content.
\nThe v1 lifecycle, resource, and sync operations remain covered in the reference. Keep their original paths and response models when maintaining existing clients. New v2 clients must account for the data envelope, cursor fields, and additional query/download/metadata capabilities. Changing /v1 to /v2 without updating parsing is not a migration plan.
A provider describes an integration, an action describes an operation it can perform, and a connection is an authorized instance of that integration in your organization. A trigger descriptor explains an event source; reading it does not activate a trigger.
\n/v2/providers and choose a returned provider ID./v2/providers/{provider_id} for its details./v2/providers/{provider_id}/actions, then GET the chosen /{action_id} for the actual input/output schema./v2/connections?provider_id=... and choose an accessible compatible connection. A needs_reconnection status requires repair in StackAI./v2/providers/{provider_id}/actions/{action_id}/run with connection_id when required and the action-specific inputs.{\n "connection_id": "00000000-0000-4000-8000-000000000001",\n "inputs": {"ACTION_SPECIFIC_FIELD": "VALUE_FROM_YOUR_APPLICATION"}\n}\nThe UUID and field above are placeholders, not a universally valid action request. Do not infer an action's inputs from its name. Omit connection_id only for actions whose contract supports that. The call is synchronous; inspect returned outputs and errors.
The public API lists existing connections; it does not define a connection-create operation in this contract. Establish or reconnect credentials through StackAI's supported connection flow. Users see only connections available through their roles/sharing; an empty list need not mean the organization has none.
\nUse the trigger list/detail routes to discover configuration requirements. There is no trigger-enable operation in this public catalog. Actions can send messages, update records, or otherwise change third-party systems, so use a test connection first and reconcile ambiguous failures before retrying.
\nUse a connected Linear account to retrieve an issue's title and status. This is a read operation; it does not create or change an issue. First establish a Linear connection in StackAI and confirm your key has connections.read and connections.use.
Discover the action's current contract and the connections available to you:
\ncurl --fail-with-body -sS "$STACKAI_BASE_URL/v2/providers/linear/actions/get_issue" \\\n -H "Authorization: Bearer $STACKAI_API_KEY"\ncurl --fail-with-body -sS --get "$STACKAI_BASE_URL/v2/connections" \\\n -H "Authorization: Bearer $STACKAI_API_KEY" \\\n --data-urlencode 'provider_id=linear'\nChoose a healthy Linear connection from the returned list. Save its ID as CONNECTION_ID, and choose an issue that account can read. The action requires issue_id, which can be an issue identifier such as ENG-123.
Create linear-issue.json with your actual connection and issue:
{"connection_id":"00000000-0000-4000-8000-000000000001","inputs":{"issue_id":"ENG-123"}}\ncurl --fail-with-body -sS \\\n "$STACKAI_BASE_URL/v2/providers/linear/actions/get_issue/run" \\\n -H "Authorization: Bearer $STACKAI_API_KEY" \\\n -H 'Content-Type: application/json' \\\n --data-binary @linear-issue.json\nThe result is inside data.outputs. For example, an excerpt can contain:
{"data":{"outputs":{"identifier":"ENG-123","title":"Restore customer access","status":"In Progress"}}}\nUse identifier, title, and status from the response to enrich your application's routing decision. The action returns additional issue fields; consult its discovered output schema. If the connection is missing, check sharing and organization access. If it needs reconnection, repair it in StackAI. If the issue is inaccessible, use an issue the connected Linear account can read.
Suppose a workflow routes requests by returning a category such as billing. Check that a saved version still classifies a known billing request correctly. An exact-match evaluator is appropriate because the result is a category, not free-form prose.
Use a project with one selected input and one selected output. Set PROJECT_ID, PROJECT_VERSION, and STACKAI_API_KEY as in the quickstart. Read /v2/projects/{project_id}/io-schema?version={saved-version} first. Replace in-0, out-0, and legacy_input_nodes in every body below with the returned contract. Use a key with the required projects.read, evals.read, evals.create, evals.update, and evals.run permissions, plus access to the project.
This Python example uses httpx. It creates one dataset, one rule evaluator, and one experiment, then runs and reads them. It does not automatically retry writes.
import os\nimport time\nimport httpx\n\nproject_id = os.environ["PROJECT_ID"]\nversion = int(os.environ["PROJECT_VERSION"])\ncontract = {"input_kind": "legacy_input_nodes",\n "input_keys": ["in-0"], "output_node_ids": ["out-0"]}\nheaders = {"Authorization": f"Bearer {os.environ['STACKAI_API_KEY']}"}\nwith httpx.Client(base_url=os.environ["STACKAI_BASE_URL"].rstrip("/"),\n headers=headers, timeout=30) as client:\n def post(path, body):\n response = client.post(path, json=body)\n response.raise_for_status()\n return response.json()["data"]\n\n dataset = post("/v2/evals/datasets", {\n "project_id": project_id, "name": "Request classification",\n "node_contract": contract,\n })\n dataset_id = dataset["dataset_id"]\n print("Save dataset:", dataset_id)\n post(f"/v2/evals/datasets/{dataset_id}/rows", {"rows": [{\n "inputs": {"in-0": "I was charged twice for my subscription."},\n "expected_output": {"out-0": "billing"},\n }]})\n evaluator = post("/v2/evals/evaluators", {\n "project_id": project_id, "name": "Correct request category",\n "evaluator_type": "builtin_rule", "node_contract": contract,\n "config": {"rule": "exact_match", "target_output_node_id": "out-0"},\n })\n evaluator_id = evaluator["evaluator_id"]\n print("Save evaluator:", evaluator_id)\n experiment = post("/v2/evals/experiments", {\n "dataset_id": dataset_id, "project_version_id": version,\n "evaluator_ids": [evaluator_id], "name": "Saved-version category check",\n })\n experiment_id = experiment["experiment_id"]\n print("Save experiment:", experiment_id)\n job = post(f"/v2/evals/experiments/{experiment_id}/jobs", {\n "mode": "generate", "evaluator_ids": [evaluator_id],\n })\n job_id = job["job_id"]\n print("Save job:", job_id)\n deadline = time.monotonic() + 300\n while job["status"] in {"queued", "running"}:\n if time.monotonic() >= deadline:\n raise TimeoutError(f"Inspect existing job {job_id}; do not start another")\n time.sleep(2)\n response = client.get(\n f"/v2/evals/experiments/{experiment_id}/jobs/{job_id}")\n response.raise_for_status()\n job = response.json()["data"]\n print("Job status:", job["status"])\n response = client.get(f"/v2/evals/experiments/{experiment_id}/rows")\n response.raise_for_status()\n print(response.json())\nRead each row's generated_output, status, error, and scores. A matching output {"out-0":"billing"} receives an exact-match score of 1; a different category receives 0. A score of 0 is a completed comparison, not an execution error. A failed scoring status means the comparison could not complete—for example, because an expected value was missing. Inspect job and row errors before judging quality.
One case checks only one behavior. Add representative inputs and known correct categories to the dataset, then create another experiment for the version you want to compare. Experiments snapshot the dataset: editing it later does not change an existing experiment. Use a semantic or judge-based evaluator when more than one wording can be correct.
\n202 means the job was queued. Terminal statuses are completed, completed_with_failures, failed, and cancelled. Inspect row-level failures even if some outputs succeeded. Only one job may be active per experiment: a 409 can include the active job's Location/status URL and IDs in metadata. Follow that job instead of repeatedly creating jobs. A 503 on a job read means live state is temporarily unavailable; retry that GET.
Dataset detail reads expose contract-drift warnings. Dataset PATCH can re-key rows against a replacement contract; inspect the update body before using it as a simple rename. Evaluator config changes create immutable versions when material. Explicit null clears a row's expected output and clears experiment notes where documented; omitted fields remain unchanged.
\nDeleting a dataset also removes its rows and experiments. Deleting an experiment removes its snapshot rows and scores. Evaluator deletion is soft and preserves historical scores. These operations have different retention semantics.
\nGET /v2/evals/monitor-limits first. Choose a reference-free evaluator and POST a monitor with the project, evaluator, sampling rate, and daily cap. Current schema bounds sampling to greater than zero and at most 0.3 and the daily cap to 1–1000; use the limits endpoint rather than hard-coding policy forever.
Read/update the monitor, inspect /v2/evals/monitors/{monitor_id}/score-stats, tune /v2/evals/monitors/{monitor_id}/alert, and traverse /v2/evals/monitors/{monitor_id}/sampled-runs. Windows are 24h, 7d, 30d, or all. Explicit null on an alert knob resets it to the server default; omit it to keep the stored setting. Sampled-run traversal preserves an insertion cutoff. Deleting the monitor retains scores already present in run history.
POST /v2/evals/runs/{run_id}/scores using a reference-free evaluator. This appends a score; it does not overwrite history, so retries can create additional scores. List the run's scores (oldest first) or GET a specific /v2/evals/scores/{score_id}. Trace-backed scoring and score reads require analytics access in addition to their evaluation permissions.
Skills package reusable instructions and supporting files. GET /v2/skills to discover visible built-in and organization skills. GET a skill for its current published instructions/manifest; GET /versions and a numbered version for reproducible integrations.
Use multipart form fields for a simple skill:
\ncurl --fail-with-body -sS "$STACKAI_BASE_URL/v2/skills" \\\n -H "Authorization: Bearer $STACKAI_API_KEY" \\\n --form-string 'name=policy-summary' \\\n --form-string 'description=Summarize approved policy text with citations' \\\n --form-string 'instructions=Summarize only the provided policy. Cite the source and state when evidence is missing.'\nFor a bundle, send repeated files parts whose filenames preserve relative POSIX paths, or a single zip. Include the bundle's SKILL.md and valid supporting files. Do not use absolute paths or traversal paths in the bundle. Use the endpoint's validation errors to fix invalid or oversized bundles; no universal upload-size allowance is promised here.
POST /v2/skills/{skill_id}/versions to publish another version. Repeat carry_paths to retain selected files, and set base_version to the version to copy from when needed; otherwise it uses the current version. Unmentioned files are not a substitute for explicitly carried files. Supplying a changed name can rename the skill when publishing.
Save the skill ID and returned version number. Fetch that exact version when reproducibility matters instead of always using latest. Version numbers are 1-based. Conflicting names or versions can produce 409. DELETE removes an owned skill and all its versions; organization administrators may delete other organization skills. Do not treat deletion as an unpublish operation for just one version.
\nPOST /v2/webhooks/subscriptions with your HTTPS URL and desired event types:
{\n "url":"https://your-service.example.com/webhooks/stackai",\n "event_types":["run.succeeded","run.failed"]\n}\nUse an authorized credential with org.webhooks.manage. Store the signing secret returned at creation immediately; list responses cannot recover it. To replace a lost secret, create a replacement subscription and retire the old one carefully. There is no PATCH subscription operation in this contract.
Use GET /v2/runs/{run_id} as the supported way to observe a workflow's completion. Creating a webhook subscription stores its URL and selected event names; it does not enable run-event delivery. Do not replace polling with a subscription when building a run-status integration.
| Capability | \nWhat you can rely on | \n
|---|---|
| Create, list, and delete subscriptions | \nManage the URL and accepted event types through the subscription endpoints | \n
| Observe completion of a run | \nPoll the run until it reaches a terminal status | \n
| Receive a run lifecycle notification | \nSubscription creation alone does not establish this capability; it is not a replacement for run polling | \n
| Replay a delivery or inspect delivery history | \nNo public replay or delivery-history endpoint is provided | \n
Accepted subscription event names are run.started, run.step.succeeded, run.step.failed, run.succeeded, run.failed, and run.cancelled. These names describe subscription filters, not a guarantee that an event will be produced for every run. The receiver guidance below applies when webhook deliveries are enabled for your deployment.
Deliveries use the Standard Webhooks headers webhook-id, webhook-timestamp, and webhook-signature. Verify against the exact raw request body and the subscription's whsec_... secret before parsing or processing. Use a Standard Webhooks verifier with timestamp validation; JSON reserialization changes the bytes and can break verification.
Conceptual Python handler logic with the standardwebhooks package:
from standardwebhooks.webhooks import Webhook\n\n# raw_body and headers come from your HTTP framework.\n# secret comes from your secret manager, never from the incoming request.\nverified_event = Webhook(secret).verify(raw_body, headers)\nevent_id = headers["webhook-id"]\n# Atomically persist event_id and enqueue work only if it is new.\n# Return 2xx after durable acceptance; process the work asynchronously.\nCatch verification errors and reject invalid requests. Use durable, atomic deduplication; an in-memory set is insufficient across workers or restarts. Preserve the verified event's ID with your processing record. Retries reuse the same event ID and body. Do not assume event order or exactly-once delivery.
\nSuccessful 2xx responses acknowledge delivery. Redirects are not followed. Retryable client/server failures and transport failures can be retried; the current implementation has a bounded ladder of up to ten attempts with jitter. Return a suitable transient failure when you cannot durably accept work, rather than 200 and silently losing it. A 503 with numeric Retry-After can influence retry timing within server limits.
\nGET subscriptions to inventory active endpoints; DELETE a subscription to stop deliveries and remove it from that list. There is no public delivery-history or replay endpoint in this contract.
\nSCIM is a separate externally facing identity-management surface under /scim/v2. Configure it through your identity provider and StackAI's SCIM settings. Use the dedicated SCIM bearer token and application/scim+json payloads for provisioning; normal workflow API keys are not interchangeable. See the existing StackAI SCIM setup guide.
Use the discovery endpoints below to read the SCIM capabilities and schemas available in your deployment. SCIM responses follow their own protocol rather than the REST v2 envelope.
\n| Method | \nPath | \nUsage | \n
|---|---|---|
| GET | \n/scim/v2/ServiceProviderConfig | \nDiscover supported provisioning capabilities before configuring the IdP | \n
| GET | \n/scim/v2/ResourceTypes | \nDiscover Users and Groups resource types | \n
| GET | \n/scim/v2/ResourceTypes/{resource_type_id} | \nRead one resource-type descriptor | \n
| GET | \n/scim/v2/Schemas | \nDiscover schema attributes and extensions | \n
| GET | \n/scim/v2/Schemas/{schema_id} | \nRead a specific schema URI | \n
| GET | \n/scim/v2/Users | \nList/filter users with startIndex and count | \n
| POST | \n/scim/v2/Users | \nProvision a user from a SCIM user body; retain returned ID | \n
| GET | \n/scim/v2/Users/{user_id} | \nRead the provisioned user by SCIM ID | \n
| PUT | \n/scim/v2/Users/{user_id} | \nReplace the user's supported attributes using a complete desired representation | \n
| PATCH | \n/scim/v2/Users/{user_id} | \nApply SCIM PatchOp operations, such as updating active state | \n
| DELETE | \n/scim/v2/Users/{user_id} | \nDeprovision the user; treat this as an access-changing action | \n
| GET | \n/scim/v2/Groups | \nList/filter groups; use the returned SCIM IDs | \n
| POST | \n/scim/v2/Groups | \nCreate a group and supported membership representation | \n
| GET | \n/scim/v2/Groups/{group_id} | \nRead a group and its members | \n
| PUT | \n/scim/v2/Groups/{group_id} | \nReplace the supported group representation | \n
| PATCH | \n/scim/v2/Groups/{group_id} | \nAdd/remove members with SCIM PatchOp semantics | \n
| DELETE | \n/scim/v2/Groups/{group_id} | \nDelete the group; review membership/access effects first | \n
Read discovery → match existing users by a supported filter → create or update → reconcile group membership → verify by GET → deprovision when the IdP revokes access. User filters include userName eq "person@example.com", externalId eq "idp-id", and supported email filters. URL-encode the filter. Pagination is 1-based; count=0 requests totals without Resources. A SCIM ID, an external IdP ID, and a StackAI project/user identifier should not be guessed interchangeable.
curl --fail-with-body -sS --get "$STACKAI_BASE_URL/scim/v2/Users" \\\n -H "Authorization: Bearer $STACKAI_SCIM_TOKEN" \\\n -H 'Accept: application/scim+json' \\\n --data-urlencode 'filter=userName eq "person@example.com"' \\\n --data-urlencode 'startIndex=1' --data-urlencode 'count=100'\nSCIM error responses and Resources/totalResults pagination follow the provisioning protocol, not the v2 REST data envelope. Do not use the generic REST client's parsing rules without a SCIM adapter.
| Symptom | \nCheck first | \nNext action | \n
|---|---|---|
| 401 | \nCorrect Bearer syntax, credential type, expiry/revocation, organization | \nReplace/refresh through the supported credential flow; do not retry unchanged credentials | \n
| 403 | \nKey scopes, owner's permissions, resource/folder access, publication or logging rules | \nInspect the endpoint and error metadata; request only the missing permission | \n
| 404 | \nCorrect deployment, resource ID, organization, saved version, resource access | \nVerify the ID with an authorized read; absence may intentionally conceal access | \n
| 400/422 | \nJSON shape, extra fields, required keys, enum values, UUIDs, multipart names | \nCompare with the exact endpoint schema; preserve safe field-level errors | \n
| 402 on run start/resume | \nOrganization usage allowance | \nResolve the usage limit before trying again | \n
| 409 | \nActive job, already-resumed run, cancellation state, name/version collision | \nRead current state; do not blindly repeat the write | \n
| 406 on legacy resume | \nSSE requested for a trigger-backed continuation | \nUse the supported non-SSE/polling path | \n
| 429 | \nDeployment throttling | \nBack off, honor Retry-After when available, lower concurrency | \n
| 500 after a write | \nSide effect may already have occurred | \nReconcile existing runs/resources before retrying | \n
| 503 on run reservation | \nDispatch did not occur according to this route's contract | \nRetry within a bounded policy | \n
| 503 on eval job GET | \nLive job state temporarily unavailable | \nRetry the same status URL, not job creation | \n
| Empty KB search | \nIndexing status, source access, query strategy, actual content | \nWait for indexed resources and test with a known document phrase | \n
| Empty connection list | \nProvider filter and connection sharing | \nCheck access in StackAI and reconnect degraded entries | \n
| Missing pause payload | \nRead and run permissions both present | \nUse a credential permitted to resume; keep the token out of logs | \n
Log method, route template, status, safe error code, latency, and returned resource IDs. Redact authorization, resume tokens, webhook secrets, signed URLs, and sensitive input/output. The public error envelope can contain errors, detail, response_code, and meta; legacy responses can differ. Do not assume every exception conforms to one JSON shape.
Before shipping: test against a nonproduction project; pin the intended saved workflow version; validate the input contract; configure timeouts and safe retry limits; persist asynchronous IDs; verify all terminal states and pauses; exercise pagination beyond one page; check key revocation; and test your webhook signature/deduplication path if used.
\nNo universal numeric request-rate, execution-time, or file-size limit is asserted by this documentation. Use schema-enforced bounds, deployment policy, and observed response headers. Do not infer an SLA or supported SDK from illustrative HTTP examples.
\nThe API version is part of the route. Keep an existing v1 client on v1 parsing until you intentionally migrate it. Use v2 for the capabilities it supports; use the inference interface when you need its inline response or streaming contract. Calling an interface legacy does not by itself announce a retirement date.
\nBefore changing versions, compare the authentication method, input body, response envelope, pagination, status values, and project-version selector. For example, v2 run creation accepts {project_id, project_version, input}, while inference accepts the input map itself. A v2 project_version of -1 selects a draft; an inference version of -1 selects published content.
Download the OpenAPI specification to generate a client or validate request and response shapes. Its document version is separate from both route versions and saved project versions. Examples show the documented shapes; replace project IDs, connection IDs, and input keys with your own values. The reference covers the public operations listed in its navigation. Undocumented browser routes and provider authorization callbacks are not public integration endpoints.
\n"},"paths":{"/inference/v0/runs/{org_id}/{run_id}":{"get":{"tags":["endpoint-getRun"],"summary":"Get Run","description":"Get the status of a run, including the human-in-the-loop pause when waiting.\n\n**How to use**\n\nUse this to observe a legacy run or retrieve its pause context. Read `state` and `pause` from this response, not the v2 `data.status`/`pending_input` fields. Terminal legacy success is `COMPLETED`.\n\n**Authentication and permissions**\n\nRequired permissions: `projects.read`. Resource and owner access checks also apply.","operationId":"getRun","security":[{"LegacyAPIKeyBearer":[]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","title":"Org Id"}},{"name":"run_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The run ID to fetch the status for.","title":"Run Id","x-gitbook-description-html":"The run ID to fetch the status for.
\n"},"description":"The run ID to fetch the status for.","x-gitbook-description-html":"The run ID to fetch the status for.
\n"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunStatusResponse"}}},"x-gitbook-description-html":"Successful Response
\n"},"404":{"description":"Run not found or does not belong to this organization","x-gitbook-description-html":"Run not found or does not belong to this organization
\n"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"x-gitbook-description-html":"Validation Error
\n"}},"x-required-scope":"projects.read","x-required-scopes":["projects.read"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS \\\n \"$STACKAI_BASE_URL/inference/v0/runs/${ORG_ID}/${RUN_ID}\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\""}],"x-gitbook-description-html":"Get the status of a run, including the human-in-the-loop pause when waiting.
\nHow to use
\nUse this to observe a legacy run or retrieve its pause context. Read state and pause from this response, not the v2 data.status/pending_input fields. Terminal legacy success is COMPLETED.
Authentication and permissions
\nRequired permissions: projects.read. Resource and owner access checks also apply.
The paused run ID to resume.
\n"},"description":"The paused run ID to resume.","x-gitbook-description-html":"The paused run ID to resume.
\n"},{"name":"verbose","in":"query","required":false,"schema":{"type":"boolean","description":"Return the full model when streaming an in-process resume over SSE.","default":true,"title":"Verbose","x-gitbook-description-html":"Return the full model when streaming an in-process resume over SSE.
\n"},"description":"Return the full model when streaming an in-process resume over SSE.","x-gitbook-description-html":"Return the full model when streaming an in-process resume over SSE.
\n"},{"name":"execution_mode","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/ExecutionMode"},{"type":"null"}],"description":"Set to 'remote' to watch the continuation over a WebSocket (202 + handle) instead of blocking on this request; only valid for runs that resume out of band (Temporal/trigger) — sending it for an in-process run returns 409. Omit to resume inline (JSON, or SSE when the request sends Accept: text/event-stream).","title":"Execution Mode","x-gitbook-description-html":"Set to 'remote' to watch the continuation over a WebSocket (202 + handle) instead of blocking on this request; only valid for runs that resume out of band (Temporal/trigger) — sending it for an in-process run returns 409. Omit to resume inline (JSON, or SSE when the request sends Accept: text/event-stream).
\n"},"description":"Set to 'remote' to watch the continuation over a WebSocket (202 + handle) instead of blocking on this request; only valid for runs that resume out of band (Temporal/trigger) — sending it for an in-process run returns 409. Omit to resume inline (JSON, or SSE when the request sends Accept: text/event-stream).","x-gitbook-description-html":"Set to 'remote' to watch the continuation over a WebSocket (202 + handle) instead of blocking on this request; only valid for runs that resume out of band (Temporal/trigger) — sending it for an in-process run returns 409. Omit to resume inline (JSON, or SSE when the request sends Accept: text/event-stream).
\n"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResumeRunRequest","description":"Resume token plus the human response to inject into the paused run.","x-gitbook-description-html":"Resume token plus the human response to inject into the paused run.
\n"},"example":{"resume_token":"TOKEN_FROM_PAUSE","response":"THE_HUMAN_ANSWER"}}}},"responses":{"200":{"description":"Returns the run-result envelope (same shape as a normal run): in-memory runs resume synchronously with a terminal state + outputs; out-of-band (Temporal/trigger) runs return state=RESUMED with empty outputs, and the client polls GET /runs/{org_id}/{run_id} for completion. With Accept: text/event-stream the continuation streams back as SSE for in-process and live Temporal runs (trigger-backed runs return 406).","content":{"application/json":{"schema":{"type":"object"}},"text/event-stream":{"schema":{"type":"string"}}},"x-gitbook-description-html":"Returns the run-result envelope (same shape as a normal run): in-memory runs resume synchronously with a terminal state + outputs; out-of-band (Temporal/trigger) runs return state=RESUMED with empty outputs, and the client polls GET /runs/{org_id}/{run_id} for completion. With Accept: text/event-stream the continuation streams back as SSE for in-process and live Temporal runs (trigger-backed runs return 406).
\n"},"202":{"description":"Returned with execution_mode=remote and no Accept: text/event-stream on a durable run: the continuation runs in the background; the body carries the run_id and a WebSocket handle. Watch the room or poll GET /runs/{org_id}/{run_id} for completion.","x-gitbook-description-html":"Returned with execution_mode=remote and no Accept: text/event-stream on a durable run: the continuation runs in the background; the body carries the run_id and a WebSocket handle. Watch the room or poll GET /runs/{org_id}/{run_id} for completion.
\n"},"401":{"description":"Invalid or expired resume token","x-gitbook-description-html":"Invalid or expired resume token
\n"},"403":{"description":"Run is paused on a step not resumable via the public API (only ask-human pauses are supported).","x-gitbook-description-html":"Run is paused on a step not resumable via the public API (only ask-human pauses are supported).
\n"},"404":{"description":"Run not found or does not belong to this organization","x-gitbook-description-html":"Run not found or does not belong to this organization
\n"},"406":{"description":"Accept: text/event-stream was sent for a trigger-backed run, which has no event stream to relay. Retry without the Accept header and poll GET /runs/{org_id}/{run_id}, or pass execution_mode=remote for a 202 + WebSocket handle.","x-gitbook-description-html":"Accept: text/event-stream was sent for a trigger-backed run, which has no event stream to relay. Retry without the Accept header and poll GET /runs/{org_id}/{run_id}, or pass execution_mode=remote for a 202 + WebSocket handle.
\n"},"409":{"description":"Run is not paused/resumable, or execution_mode=remote was sent for an in-process run that can only resume inline.","x-gitbook-description-html":"Run is not paused/resumable, or execution_mode=remote was sent for an in-process run that can only resume inline.
\n"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"x-gitbook-description-html":"Validation Error
\n"}},"x-required-scope":"projects.run","x-required-scopes":["projects.run"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS \\\n \"$STACKAI_BASE_URL/inference/v0/runs/${ORG_ID}/${RUN_ID}/resume\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\" \\\n -H 'Content-Type: application/json' \\\n --data-binary @request.json"}],"x-gitbook-description-html":"Resume a paused run that is waiting on a human-in-the-loop response.
\nHow to use
\nRead the current pause first and submit its token with the actual human answer. A RESUMED response can be nonterminal. Remote resume is only supported for out-of-band execution; SSE is not supported for trigger-backed runs. Inspect 406/409 responses before choosing a supported continuation mode.
Authentication and permissions
\nRequired permissions: projects.run. Resource and owner access checks also apply.
Prepare request.json
\nSave the example body below as request.json for the curl sample. Replace example IDs, node keys, and dynamic configuration with values for your organization; these are illustrative, not pre-existing resources.
{\n "resume_token": "TOKEN_FROM_PAUSE",\n "response": "THE_HUMAN_ANSWER"\n}\nThe flow ID. Learn how to get it.
\n"},"description":"The flow ID. [Learn how to get it](/docs/api-reference/how-to-get-flow-id).","x-gitbook-description-html":"The flow ID. Learn how to get it.
\n"},{"name":"version","in":"query","required":false,"schema":{"type":"integer","description":"Version of the flow","default":-1,"title":"Version","x-gitbook-description-html":"Version of the flow
\n"},"description":"Version of the flow","x-gitbook-description-html":"Version of the flow
\n"},{"name":"verbose","in":"query","required":false,"schema":{"type":"boolean","description":"Return the full model","default":true,"title":"Verbose","x-gitbook-description-html":"Return the full model
\n"},"description":"Return the full model","x-gitbook-description-html":"Return the full model
\n"},{"name":"delta","in":"query","required":false,"schema":{"type":"boolean","description":"Stream deltas instead of full output. Only applies when streaming (Accept: text/event-stream).","default":true,"title":"Delta","x-gitbook-description-html":"Stream deltas instead of full output. Only applies when streaming (Accept: text/event-stream).
\n"},"description":"Stream deltas instead of full output. Only applies when streaming (Accept: text/event-stream).","x-gitbook-description-html":"Stream deltas instead of full output. Only applies when streaming (Accept: text/event-stream).
\n"},{"name":"prefix","in":"query","required":false,"schema":{"type":"boolean","description":"Add a prefix to the output. Only applies when streaming (Accept: text/event-stream).","default":false,"title":"Prefix","x-gitbook-description-html":"Add a prefix to the output. Only applies when streaming (Accept: text/event-stream).
\n"},"description":"Add a prefix to the output. Only applies when streaming (Accept: text/event-stream).","x-gitbook-description-html":"Add a prefix to the output. Only applies when streaming (Accept: text/event-stream).
\n"},{"name":"execution_mode","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/ExecutionMode"},{"type":"null"}],"description":"Set to 'remote' to run durably in the background and receive a 202 with a WebSocket handle. Omit for inline execution (JSON, or SSE when the request sends Accept: text/event-stream).","title":"Execution Mode","x-gitbook-description-html":"Set to 'remote' to run durably in the background and receive a 202 with a WebSocket handle. Omit for inline execution (JSON, or SSE when the request sends Accept: text/event-stream).
\n"},"description":"Set to 'remote' to run durably in the background and receive a 202 with a WebSocket handle. Omit for inline execution (JSON, or SSE when the request sends Accept: text/event-stream).","x-gitbook-description-html":"Set to 'remote' to run durably in the background and receive a 202 with a WebSocket handle. Omit for inline execution (JSON, or SSE when the request sends Accept: text/event-stream).
\n"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Input parameters for the flow","title":"Inputs","x-gitbook-description-html":"Input parameters for the flow
\n"},"example":{"in-0":"Summarize our refund policy"}}}},"responses":{"200":{"description":"The run-result envelope (same InferenceResponse shape as resume): a terminal state + outputs, or state=PAUSED with the pause payload when the run pauses on a human-in-the-loop step. With Accept: text/event-stream the run streams back as SSE InferenceResponse frames instead.","content":{"application/json":{"schema":{"type":"object"}},"text/event-stream":{"schema":{"type":"string"}}},"x-gitbook-description-html":"The run-result envelope (same InferenceResponse shape as resume): a terminal state + outputs, or state=PAUSED with the pause payload when the run pauses on a human-in-the-loop step. With Accept: text/event-stream the run streams back as SSE InferenceResponse frames instead.
\n"},"202":{"description":"Returned with execution_mode=remote and no Accept: text/event-stream: the run executes durably in the background; the body carries the run_id and a WebSocket handle to stream updates. Poll GET /runs/{org_id}/{run_id} for the terminal state.","x-gitbook-description-html":"Returned with execution_mode=remote and no Accept: text/event-stream: the run executes durably in the background; the body carries the run_id and a WebSocket handle to stream updates. Poll GET /runs/{org_id}/{run_id} for the terminal state.
\n"},"403":{"description":"Project is not published","x-gitbook-description-html":"Project is not published
\n"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"x-gitbook-description-html":"Validation Error
\n"}},"x-required-scope":"projects.run","x-required-scopes":["projects.run"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS \\\n \"$STACKAI_BASE_URL/inference/v0/run/${ORG_ID}/${FLOW_ID}\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\" \\\n -H 'Content-Type: application/json' \\\n --data-binary @request.json"}],"x-gitbook-description-html":"Run a flow and get the result.
\nHow to use
\nSend the workflow input map as the entire JSON body. The flow must be published. Omit execution_mode for inline JSON or SSE; request remote without SSE for a 202 background handle. Do not resend after a timeout without checking whether execution started.
Authentication and permissions
\nRequired permissions: projects.run. Resource and owner access checks also apply.
Prepare request.json
\nSave the example body below as request.json for the curl sample. Replace example IDs, node keys, and dynamic configuration with values for your organization; these are illustrative, not pre-existing resources.
{\n "in-0": "Summarize our refund policy"\n}\nOptional identifier for the page that should be returned. If it is not provided, the first page will be returned.
\n"},"description":"Optional identifier for the page that should be returned. If it is not provided, the first page will be returned.","x-gitbook-description-html":"Optional identifier for the page that should be returned. If it is not provided, the first page will be returned.
\n"},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Number of items to be returned in the page.","default":50,"title":"Page Size","x-gitbook-description-html":"Number of items to be returned in the page.
\n"},"description":"Number of items to be returned in the page.","x-gitbook-description-html":"Number of items to be returned in the page.
\n"},{"name":"direction","in":"query","required":false,"schema":{"$ref":"#/components/schemas/PaginationDirection","description":"Direction for pagination: 'next' to advance through pages (older items), 'prev' to go back (newer items)","default":"next","x-gitbook-description-html":"Direction for pagination: 'next' to advance through pages (older items), 'prev' to go back (newer items)
\n"},"description":"Direction for pagination: 'next' to advance through pages (older items), 'prev' to go back (newer items)","x-gitbook-description-html":"Direction for pagination: 'next' to advance through pages (older items), 'prev' to go back (newer items)
\n"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeBaseResourcesResponse"}}},"x-gitbook-description-html":"Successful Response
\n"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"x-gitbook-description-html":"Validation Error
\n"}},"x-required-scopes":["kbs.read"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS \\\n \"$STACKAI_BASE_URL/v1/knowledge-bases/${KNOWLEDGE_BASE_ID}/resources\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\""}],"x-gitbook-description-html":"List files in the knowledge base with optional cursor pagination.
\nHow to use
\nList resources and inspect processing status. Use cursor pagination and retain resource_id for detail reads. Do not treat a listed pending/parsed resource as indexed.
\nAuthentication and permissions
\nRequired permissions: kbs.read. Resource and owner access checks also apply.
Successful Response
\n"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"x-gitbook-description-html":"Validation Error
\n"}},"x-required-scopes":["kbs.index"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS \\\n \"$STACKAI_BASE_URL/v1/knowledge-bases/${KNOWLEDGE_BASE_ID}/resources\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\" \\\n -F 'file=@document.pdf'"}],"x-gitbook-description-html":"Upload a file directly to a knowledge base and start indexing.
\nThis endpoint allows API users to upload files directly without needing to use\npresigned URLs. The file is uploaded to storage and indexing is started automatically.\nReturns the resource ID so callers can poll for indexing status.
\nHow to use
\nUpload multipart field file (singular). Indexing starts automatically. Save the resource_id from the 202 response and poll resource GET until indexed or error. Do not set the multipart boundary yourself or re-upload while waiting.
\nAuthentication and permissions
\nRequired permissions: kbs.index. Resource and owner access checks also apply.
Successful Response
\n"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"x-gitbook-description-html":"Validation Error
\n"}},"x-required-scopes":["kbs.read"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS \\\n \"$STACKAI_BASE_URL/v1/knowledge-bases/${KNOWLEDGE_BASE_ID}/resources/${RESOURCE_ID}\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\""}],"x-gitbook-description-html":"Get one file resource by ID from the knowledge base.
\nHow to use
\nPoll this after upload/sync. indexed indicates readiness; error needs investigation. pending_delete/deleted should not be treated as available search content.
\nAuthentication and permissions
\nRequired permissions: kbs.read. Resource and owner access checks also apply.
Successful Response
\n"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"x-gitbook-description-html":"Validation Error
\n"}},"x-required-scopes":["kbs.delete"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS -X DELETE \\\n \"$STACKAI_BASE_URL/v1/knowledge-bases/${KNOWLEDGE_BASE_ID}/resources/${RESOURCE_ID}\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\""}],"x-gitbook-description-html":"Delete a file resource by ID.
\nHow to use
\nDelete the specified resource from its KB. Verify both IDs before removing content used by downstream retrieval. A 204 has no body.
\nAuthentication and permissions
\nRequired permissions: kbs.delete. Resource and owner access checks also apply.
Successful Response
\n"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"x-gitbook-description-html":"Validation Error
\n"}},"x-required-scopes":["kbs.sync"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS -X POST \\\n \"$STACKAI_BASE_URL/v1/knowledge-bases/${KNOWLEDGE_BASE_ID}/sync\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\""}],"x-gitbook-description-html":"Synchronize the knowledge base.
\nHow to use
\nRequests a one-shot synchronization. A 202 means accepted, not that every resource is indexed. Inspect KB/resource status before querying updated source content.
\nAuthentication and permissions
\nRequired permissions: kbs.sync. Resource and owner access checks also apply.
Optional identifier for the page that should be returned. If it is not provided, the first page will be returned.
\n"},"description":"Optional identifier for the page that should be returned. If it is not provided, the first page will be returned.","x-gitbook-description-html":"Optional identifier for the page that should be returned. If it is not provided, the first page will be returned.
\n"},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"minimum":1,"description":"Number of items to be returned in the page.","default":50,"title":"Page Size","x-gitbook-description-html":"Number of items to be returned in the page.
\n"},"description":"Number of items to be returned in the page.","x-gitbook-description-html":"Number of items to be returned in the page.
\n"},{"name":"direction","in":"query","required":false,"schema":{"$ref":"#/components/schemas/PaginationDirection","description":"Direction for pagination: 'next' to advance through pages (older items), 'prev' to go back (newer items)","default":"next","x-gitbook-description-html":"Direction for pagination: 'next' to advance through pages (older items), 'prev' to go back (newer items)
\n"},"description":"Direction for pagination: 'next' to advance through pages (older items), 'prev' to go back (newer items)","x-gitbook-description-html":"Direction for pagination: 'next' to advance through pages (older items), 'prev' to go back (newer items)
\n"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/KnowledgeBaseResponse"},"title":"Response Listknowledgebases"}}},"x-gitbook-description-html":"Successful Response
\n"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"x-gitbook-description-html":"Validation Error
\n"}},"x-required-scopes":["kbs.read"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS \\\n \"$STACKAI_BASE_URL/v1/knowledge-bases\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\""}],"x-gitbook-description-html":"List all available knowledge bases for the specified flow.
\nHow to use
\nDiscover KBs available to the authenticated caller; select the returned knowledge_base_id. The v1 response is a bare array, so do not expect v2 cursor/envelope fields.
\nAuthentication and permissions
\nRequired permissions: kbs.read. Resource and owner access checks also apply.
Successful Response
\n"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"x-gitbook-description-html":"Validation Error
\n"}},"x-required-scopes":["kbs.create"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS \\\n \"$STACKAI_BASE_URL/v1/knowledge-bases\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\" \\\n -H 'Content-Type: application/json' \\\n --data-binary @request.json"}],"x-gitbook-description-html":"Create a new knowledge base.
\nHow to use
\nCreate a named content store, optionally selecting existing connection or website sources. Save knowledge_base_id, then upload or synchronize content. Catalog, source, embedding-model, and sharing policies can affect admission.
\nAuthentication and permissions
\nRequired permissions: kbs.create. Resource and owner access checks also apply.
Prepare request.json
\nSave the example body below as request.json for the curl sample. Replace example IDs, node keys, and dynamic configuration with values for your organization; these are illustrative, not pre-existing resources.
{\n "name": "Support handbook",\n "description": "Approved support policies"\n}\nSuccessful Response
\n"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"x-gitbook-description-html":"Validation Error
\n"}},"x-required-scopes":["kbs.read"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS \\\n \"$STACKAI_BASE_URL/v1/knowledge-bases/${KNOWLEDGE_BASE_ID}\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\""}],"x-gitbook-description-html":"Get a knowledge base by its ID in the current organization.
\nHow to use
\nRead configuration and indexing totals before querying, changing, or deleting a KB. Existence does not mean all resources are indexed.
\nAuthentication and permissions
\nRequired permissions: kbs.read. Resource and owner access checks also apply.
Successful Response
\n"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"x-gitbook-description-html":"Validation Error
\n"}},"x-required-scopes":["kbs.update"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS -X PATCH \\\n \"$STACKAI_BASE_URL/v1/knowledge-bases/${KNOWLEDGE_BASE_ID}\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\" \\\n -H 'Content-Type: application/json' \\\n --data-binary @request.json"}],"x-gitbook-description-html":"Update a knowledge base.
\nHow to use
\nSend only fields to change and follow their nullability rules. Source and indexing configuration changes may need synchronization/reindexing; review resource readiness afterward.
\nAuthentication and permissions
\nRequired permissions: kbs.update. Resource and owner access checks also apply.
Prepare request.json
\nSave the example body below as request.json for the curl sample. Replace example IDs, node keys, and dynamic configuration with values for your organization; these are illustrative, not pre-existing resources.
{\n "name": "Updated support handbook"\n}\nSuccessful Response
\n"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"x-gitbook-description-html":"Validation Error
\n"}},"x-required-scopes":["kbs.delete"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS -X DELETE \\\n \"$STACKAI_BASE_URL/v1/knowledge-bases/${KNOWLEDGE_BASE_ID}\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\""}],"x-gitbook-description-html":"Delete a knowledge base by its ID.
\nHow to use
\nRemoves the knowledge base. Check dependent workflows and retain necessary source material before deletion. A 204 response has no JSON body.
\nAuthentication and permissions
\nRequired permissions: kbs.delete. Resource and owner access checks also apply.
Optional identifier for the page that should be returned. If it is not provided, the first page will be returned.
\n"},"description":"Optional identifier for the page that should be returned. If it is not provided, the first page will be returned.","x-gitbook-description-html":"Optional identifier for the page that should be returned. If it is not provided, the first page will be returned.
\n"},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"minimum":1,"description":"Number of items to be returned in the page.","default":50,"title":"Page Size","x-gitbook-description-html":"Number of items to be returned in the page.
\n"},"description":"Number of items to be returned in the page.","x-gitbook-description-html":"Number of items to be returned in the page.
\n"},{"name":"direction","in":"query","required":false,"schema":{"$ref":"#/components/schemas/PaginationDirection","description":"Direction for pagination: 'next' to advance through pages (older items), 'prev' to go back (newer items)","default":"next","x-gitbook-description-html":"Direction for pagination: 'next' to advance through pages (older items), 'prev' to go back (newer items)
\n"},"description":"Direction for pagination: 'next' to advance through pages (older items), 'prev' to go back (newer items)","x-gitbook-description-html":"Direction for pagination: 'next' to advance through pages (older items), 'prev' to go back (newer items)
\n"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CursorPaginatedResponse_KnowledgeBaseResponseV2_"}}},"x-gitbook-description-html":"Successful Response
\n"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"x-gitbook-description-html":"Validation Error
\n"}},"x-required-scopes":["kbs.read"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS \\\n \"$STACKAI_BASE_URL/v2/knowledge-bases\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\""}],"x-gitbook-description-html":"List knowledge bases available to the caller, newest first.
\nHow to use
\nDiscover KBs available to the authenticated caller; select the returned knowledge_base_id. Read items under data and follow next_cursor. Read successful resource payloads under data when a body is returned.
\nAuthentication and permissions
\nRequired permissions: kbs.read. Resource and owner access checks also apply.
Successful Response
\n"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"x-gitbook-description-html":"Validation Error
\n"}},"x-required-scopes":["kbs.create"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS \\\n \"$STACKAI_BASE_URL/v2/knowledge-bases\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\" \\\n -H 'Content-Type: application/json' \\\n --data-binary @request.json"}],"x-gitbook-description-html":"Create a new knowledge base.
\nHow to use
\nCreate a named content store, optionally selecting existing connection or website sources. Save knowledge_base_id, then upload or synchronize content. Catalog, source, embedding-model, and sharing policies can affect admission. Read successful resource payloads under data when a body is returned.
\nAuthentication and permissions
\nRequired permissions: kbs.create. Resource and owner access checks also apply.
Prepare request.json
\nSave the example body below as request.json for the curl sample. Replace example IDs, node keys, and dynamic configuration with values for your organization; these are illustrative, not pre-existing resources.
{\n "name": "Support handbook",\n "description": "Approved support policies"\n}\nSuccessful Response
\n"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"x-gitbook-description-html":"Validation Error
\n"}},"x-required-scopes":["kbs.read"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS \\\n \"$STACKAI_BASE_URL/v2/knowledge-bases/${KNOWLEDGE_BASE_ID}\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\""}],"x-gitbook-description-html":"Get a knowledge base by its ID.
\nHow to use
\nRead configuration and indexing totals before querying, changing, or deleting a KB. Existence does not mean all resources are indexed. Read successful resource payloads under data when a body is returned.
\nAuthentication and permissions
\nRequired permissions: kbs.read. Resource and owner access checks also apply.
Successful Response
\n"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"x-gitbook-description-html":"Validation Error
\n"}},"x-required-scopes":["kbs.update"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS -X PATCH \\\n \"$STACKAI_BASE_URL/v2/knowledge-bases/${KNOWLEDGE_BASE_ID}\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\" \\\n -H 'Content-Type: application/json' \\\n --data-binary @request.json"}],"x-gitbook-description-html":"Update a knowledge base.
\nHow to use
\nSend only fields to change and follow their nullability rules. Source and indexing configuration changes may need synchronization/reindexing; review resource readiness afterward. Read successful resource payloads under data when a body is returned.
\nAuthentication and permissions
\nRequired permissions: kbs.update. Resource and owner access checks also apply.
Prepare request.json
\nSave the example body below as request.json for the curl sample. Replace example IDs, node keys, and dynamic configuration with values for your organization; these are illustrative, not pre-existing resources.
{\n "name": "Updated support handbook"\n}\nSuccessful Response
\n"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"x-gitbook-description-html":"Validation Error
\n"}},"x-required-scopes":["kbs.delete"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS -X DELETE \\\n \"$STACKAI_BASE_URL/v2/knowledge-bases/${KNOWLEDGE_BASE_ID}\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\""}],"x-gitbook-description-html":"Delete a knowledge base by its ID.
\nHow to use
\nRemoves the knowledge base. Check dependent workflows and retain necessary source material before deletion. A 204 response has no JSON body. Read successful resource payloads under data when a body is returned.
\nAuthentication and permissions
\nRequired permissions: kbs.delete. Resource and owner access checks also apply.
Successful Response
\n"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"x-gitbook-description-html":"Validation Error
\n"}},"x-required-scopes":["kbs.read"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS \\\n \"$STACKAI_BASE_URL/v2/knowledge-bases/${KNOWLEDGE_BASE_ID}/metadata-schemas\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\""}],"x-gitbook-description-html":"Get the user and dataloader metadata schemas for a knowledge base.
\nHow to use
\nInspect the user and dataloader metadata schema before interpreting file metadata. These metadata descriptions are not the content-search endpoint.
\nAuthentication and permissions
\nRequired permissions: kbs.read. Resource and owner access checks also apply.
Optional identifier for the page that should be returned. If it is not provided, the first page will be returned.
\n"},"description":"Optional identifier for the page that should be returned. If it is not provided, the first page will be returned.","x-gitbook-description-html":"Optional identifier for the page that should be returned. If it is not provided, the first page will be returned.
\n"},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Number of items to be returned in the page.","default":50,"title":"Page Size","x-gitbook-description-html":"Number of items to be returned in the page.
\n"},"description":"Number of items to be returned in the page.","x-gitbook-description-html":"Number of items to be returned in the page.
\n"},{"name":"direction","in":"query","required":false,"schema":{"$ref":"#/components/schemas/PaginationDirection","description":"Direction for pagination: 'next' to advance through pages (older items), 'prev' to go back (newer items)","default":"next","x-gitbook-description-html":"Direction for pagination: 'next' to advance through pages (older items), 'prev' to go back (newer items)
\n"},"description":"Direction for pagination: 'next' to advance through pages (older items), 'prev' to go back (newer items)","x-gitbook-description-html":"Direction for pagination: 'next' to advance through pages (older items), 'prev' to go back (newer items)
\n"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CursorPaginatedResponse_KnowledgeBaseFileResponseV2_"}}},"x-gitbook-description-html":"Successful Response
\n"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"x-gitbook-description-html":"Validation Error
\n"}},"x-required-scopes":["kbs.read"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS \\\n \"$STACKAI_BASE_URL/v2/knowledge-bases/${KNOWLEDGE_BASE_ID}/resources\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\""}],"x-gitbook-description-html":"List all files in the knowledge base (flat).
\nHow to use
\nList resources and inspect processing status. Use cursor pagination and retain resource_id for detail reads. Do not treat a listed pending/parsed resource as indexed. Read successful resource payloads under data when a body is returned.
\nAuthentication and permissions
\nRequired permissions: kbs.read. Resource and owner access checks also apply.
Successful Response
\n"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"x-gitbook-description-html":"Validation Error
\n"}},"x-required-scopes":["kbs.index"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS \\\n \"$STACKAI_BASE_URL/v2/knowledge-bases/${KNOWLEDGE_BASE_ID}/resources\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\" \\\n -F 'file=@document.pdf'"}],"x-gitbook-description-html":"Upload a file directly and start indexing; poll the resource GET for status.
\nHow to use
\nUpload multipart field file (singular). Indexing starts automatically. Save the resource_id from the 202 response and poll resource GET until indexed or error. Do not set the multipart boundary yourself or re-upload while waiting. Read successful resource payloads under data when a body is returned.
\nAuthentication and permissions
\nRequired permissions: kbs.index. Resource and owner access checks also apply.
Successful Response
\n"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"x-gitbook-description-html":"Validation Error
\n"}},"x-required-scopes":["kbs.read"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS \\\n \"$STACKAI_BASE_URL/v2/knowledge-bases/${KNOWLEDGE_BASE_ID}/resources/${RESOURCE_ID}\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\""}],"x-gitbook-description-html":"Get one file resource by ID.
\nHow to use
\nPoll this after upload/sync. indexed indicates readiness; error needs investigation. pending_delete/deleted should not be treated as available search content. Read successful resource payloads under data when a body is returned.
\nAuthentication and permissions
\nRequired permissions: kbs.read. Resource and owner access checks also apply.
Successful Response
\n"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"x-gitbook-description-html":"Validation Error
\n"}},"x-required-scopes":["kbs.delete"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS -X DELETE \\\n \"$STACKAI_BASE_URL/v2/knowledge-bases/${KNOWLEDGE_BASE_ID}/resources/${RESOURCE_ID}\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\""}],"x-gitbook-description-html":"Delete a file resource by ID.
\nHow to use
\nDelete the specified resource from its KB. Verify both IDs before removing content used by downstream retrieval. A 204 has no body. Read successful resource payloads under data when a body is returned.
\nAuthentication and permissions
\nRequired permissions: kbs.delete. Resource and owner access checks also apply.
Successful Response
\n"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"x-gitbook-description-html":"Validation Error
\n"}},"x-required-scopes":["kbs.read"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS \\\n \"$STACKAI_BASE_URL/v2/knowledge-bases/${KNOWLEDGE_BASE_ID}/resources/${RESOURCE_ID}/download\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\""}],"x-gitbook-description-html":"Get a signed URL to download the original file.
\nHow to use
\nReturns a signed URL for the original file. Download separately without forwarding the StackAI Authorization header. Treat the URL as temporary sensitive access, not a permanent public link.
\nAuthentication and permissions
\nRequired permissions: kbs.read. Resource and owner access checks also apply.
Successful Response
\n"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"x-gitbook-description-html":"Validation Error
\n"}},"x-required-scopes":["kbs.query"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS \\\n \"$STACKAI_BASE_URL/v2/knowledge-bases/${KNOWLEDGE_BASE_ID}/query\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\" \\\n -H 'Content-Type: application/json' \\\n --data-binary @request.json"}],"x-gitbook-description-html":"Search a knowledge base and return the most relevant results.
\nHow to use
\nSearch only after the resources you need are indexed. Choose semantic, keyword, or hybrid; top_k is 1–20. This returns retrieval results, not a generated answer. Handle empty results and preserve source attribution.
\nAuthentication and permissions
\nRequired permissions: kbs.query. Resource and owner access checks also apply.
Prepare request.json
\nSave the example body below as request.json for the curl sample. Replace example IDs, node keys, and dynamic configuration with values for your organization; these are illustrative, not pre-existing resources.
{\n "query": "What is the refund window?",\n "top_k": 5,\n "strategy": "hybrid",\n "retrieval_type": "chunks"\n}\nSuccessful Response
\n"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"x-gitbook-description-html":"Validation Error
\n"}},"x-required-scopes":["kbs.sync"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS -X POST \\\n \"$STACKAI_BASE_URL/v2/knowledge-bases/${KNOWLEDGE_BASE_ID}/sync\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\""}],"x-gitbook-description-html":"Start a one-shot synchronization of the knowledge base.
\nHow to use
\nRequests a one-shot synchronization. A 202 means accepted, not that every resource is indexed. Inspect KB/resource status before querying updated source content. Read successful resource payloads under data when a body is returned.
\nAuthentication and permissions
\nRequired permissions: kbs.sync. Resource and owner access checks also apply.
Project version to inspect: the draft, a saved version number, or latest, the newest saved version (the draft until one is saved)
\n"},"description":"Project version to inspect: the draft, a saved version number, or latest, the newest saved version (the draft until one is saved)","x-gitbook-description-html":"Project version to inspect: the draft, a saved version number, or latest, the newest saved version (the draft until one is saved)
\n"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIDataResponse_ProjectIoSchemaResponseV2_"},"example":{"data":{"input_kind":"legacy_input_nodes","inputs":[{"id":"in-0","name":"Question"}],"outputs":[{"id":"out-0","name":"Answer"}]}}}},"x-gitbook-description-html":"Successful Response
\n"},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Invalid request parameters
\n"},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Missing or invalid credentials
\n"},"403":{"description":"Denied permission, project folder access, or API-key scope (meta.required_scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"},"example":{"detail":["The credential does not have the required permission."],"meta":{"required_scope":"projects.read"}}}},"x-gitbook-description-html":"Denied permission, project folder access, or API-key scope (meta.required_scope)
\n"},"404":{"description":"Project or saved version not found in the caller's organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Project or saved version not found in the caller's organization
\n"},"4XX":{"description":"Other client errors use the same public error envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Other client errors use the same public error envelope
\n"}},"x-required-scope":"projects.read","x-required-scopes":["projects.read"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS \\\n \"$STACKAI_BASE_URL/v2/projects/${PROJECT_ID}/io-schema\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\""}],"x-gitbook-description-html":"Describe input keys and output nodes exposed by the selected project version.
\nHow to use
\nCall before constructing run inputs or evaluation contracts. Match the selected saved version to the version you intend to execute. latest is newest saved (or draft), not necessarily published. Use returned parameter identifiers, not labels from your UI.
Authentication and permissions
\nRequired permissions: projects.read. Resource and owner access checks also apply.
Case-insensitive name/description match
\n"},"description":"Case-insensitive name/description match","x-gitbook-description-html":"Case-insensitive name/description match
\n"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of items to skip.","default":0,"title":"Offset","x-gitbook-description-html":"Number of items to skip.
\n"},"description":"Number of items to skip.","x-gitbook-description-html":"Number of items to skip.
\n"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum number of items to return.","default":50,"title":"Limit","x-gitbook-description-html":"Maximum number of items to return.
\n"},"description":"Maximum number of items to return.","x-gitbook-description-html":"Maximum number of items to return.
\n"},{"name":"feeds_input_kind","in":"query","required":false,"schema":{"anyOf":[{"enum":["start_node","legacy_input_nodes"],"type":"string"},{"type":"null"}],"description":"With the other feeds_* params: keep only datasets whose capture can feed this contract","title":"Feeds Input Kind","x-gitbook-description-html":"With the other feeds_* params: keep only datasets whose capture can feed this contract
\n"},"description":"With the other feeds_* params: keep only datasets whose capture can feed this contract","x-gitbook-description-html":"With the other feeds_* params: keep only datasets whose capture can feed this contract
\n"},{"name":"feeds_input_keys","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Contract input keys; repeat the param","title":"Feeds Input Keys","x-gitbook-description-html":"Contract input keys; repeat the param
\n"},"description":"Contract input keys; repeat the param","x-gitbook-description-html":"Contract input keys; repeat the param
\n"},{"name":"feeds_output_node_ids","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Contract output node ids; repeat the param","title":"Feeds Output Node Ids","x-gitbook-description-html":"Contract output node ids; repeat the param
\n"},"description":"Contract output node ids; repeat the param","x-gitbook-description-html":"Contract output node ids; repeat the param
\n"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OffsetBasedPaginationResponse_EvalDatasetListItemResponseV2_"}}},"x-gitbook-description-html":"Successful Response
\n"},"400":{"description":"Invalid request or pagination cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Invalid request or pagination cursor
\n"},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Missing or invalid credentials
\n"},"403":{"description":"Denied permission, project folder access, or API-key scope (meta.required_scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Denied permission, project folder access, or API-key scope (meta.required_scope)
\n"},"404":{"description":"Resource not found in the caller's organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Resource not found in the caller's organization
\n"},"422":{"description":"Invalid evaluation contract, row shape, evaluator configuration, or filter combination","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Invalid evaluation contract, row shape, evaluator configuration, or filter combination
\n"},"4XX":{"description":"Client error returned in the public API envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Client error returned in the public API envelope
\n"}},"x-required-scope":"evals.read","x-required-scopes":["evals.read"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS --get \\\n \"$STACKAI_BASE_URL/v2/evals/datasets\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\" \\\n --data-urlencode \"project_id=${PROJECT_ID}\""}],"x-gitbook-description-html":"List matching project datasets; contract-drift warnings are available on detail reads.
\nHow to use
\nSupply project_id. Use search or feeds_* compatibility filters to narrow the list. Read a dataset detail for current contract-drift warnings rather than assuming a listed dataset still matches the workflow.
\nAuthentication and permissions
\nRequired permissions: evals.read. Resource and owner access checks also apply.
Created dataset URL
\n"}},"x-gitbook-description-html":"Successful Response
\n"},"400":{"description":"Invalid request or pagination cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Invalid request or pagination cursor
\n"},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Missing or invalid credentials
\n"},"403":{"description":"Denied permission, project folder access, or API-key scope (meta.required_scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Denied permission, project folder access, or API-key scope (meta.required_scope)
\n"},"404":{"description":"Resource not found in the caller's organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Resource not found in the caller's organization
\n"},"409":{"description":"Name conflict, concurrent operation, or dataset state prevents the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Name conflict, concurrent operation, or dataset state prevents the operation
\n"},"422":{"description":"Invalid evaluation contract, row shape, evaluator configuration, or filter combination","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Invalid evaluation contract, row shape, evaluator configuration, or filter combination
\n"},"4XX":{"description":"Client error returned in the public API envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Client error returned in the public API envelope
\n"}},"x-required-scope":"evals.create","x-required-scopes":["evals.create"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS \\\n \"$STACKAI_BASE_URL/v2/evals/datasets\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\" \\\n -H 'Content-Type: application/json' \\\n --data-binary @request.json"}],"x-gitbook-description-html":"Create a dataset with its input/output contract and advisory warnings.
\nHow to use
\nRead project IO first and choose exactly one input key and output node ID for node_contract. Create the dataset, save its ID, then append rows or import finished run traces.
\nAuthentication and permissions
\nRequired permissions: evals.create. Resource and owner access checks also apply.
Prepare request.json
\nSave the example body below as request.json for the curl sample. Replace example IDs, node keys, and dynamic configuration with values for your organization; these are illustrative, not pre-existing resources.
{\n "project_id": "YOUR_PROJECT_ID",\n "name": "Regression dataset",\n "node_contract": {\n "input_kind": "legacy_input_nodes",\n "input_keys": [\n "in-0"\n ],\n "output_node_ids": [\n "out-0"\n ]\n }\n}\nSuccessful Response
\n"},"400":{"description":"Invalid request or pagination cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Invalid request or pagination cursor
\n"},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Missing or invalid credentials
\n"},"403":{"description":"Denied permission, project folder access, or API-key scope (meta.required_scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Denied permission, project folder access, or API-key scope (meta.required_scope)
\n"},"404":{"description":"Resource not found in the caller's organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Resource not found in the caller's organization
\n"},"4XX":{"description":"Client error returned in the public API envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Client error returned in the public API envelope
\n"}},"x-required-scope":"evals.read","x-required-scopes":["evals.read"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS \\\n \"$STACKAI_BASE_URL/v2/evals/datasets/${DATASET_ID}\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\""}],"x-gitbook-description-html":"Read one dataset and current contract-drift warnings.
\nHow to use
\nRead before modifying a dataset or creating a regression experiment. Inspect contract-drift warnings and resolve differences from the workflow version you intend to test.
\nAuthentication and permissions
\nRequired permissions: evals.read. Resource and owner access checks also apply.
Successful Response
\n"},"400":{"description":"Invalid request or pagination cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Invalid request or pagination cursor
\n"},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Missing or invalid credentials
\n"},"403":{"description":"Denied permission, project folder access, or API-key scope (meta.required_scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Denied permission, project folder access, or API-key scope (meta.required_scope)
\n"},"404":{"description":"Resource not found in the caller's organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Resource not found in the caller's organization
\n"},"409":{"description":"Name conflict, concurrent operation, or dataset state prevents the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Name conflict, concurrent operation, or dataset state prevents the operation
\n"},"422":{"description":"Invalid evaluation contract, row shape, evaluator configuration, or filter combination","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Invalid evaluation contract, row shape, evaluator configuration, or filter combination
\n"},"4XX":{"description":"Client error returned in the public API envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Client error returned in the public API envelope
\n"}},"x-required-scope":"evals.update","x-required-scopes":["evals.update"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS -X PATCH \\\n \"$STACKAI_BASE_URL/v2/evals/datasets/${DATASET_ID}\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\" \\\n -H 'Content-Type: application/json' \\\n --data-binary @request.json"}],"x-gitbook-description-html":"Update metadata or re-key rows to a replacement contract.
\nHow to use
\nUse this for metadata or a deliberate contract replacement. Changing the contract can re-key stored rows; review the new mapping first. Omit unchanged fields.
\nAuthentication and permissions
\nRequired permissions: evals.update. Resource and owner access checks also apply.
Prepare request.json
\nSave the example body below as request.json for the curl sample. Replace example IDs, node keys, and dynamic configuration with values for your organization; these are illustrative, not pre-existing resources.
{\n "name": "Reviewed regression dataset"\n}\nSuccessful Response
\n"},"400":{"description":"Invalid request or pagination cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Invalid request or pagination cursor
\n"},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Missing or invalid credentials
\n"},"403":{"description":"Denied permission, project folder access, or API-key scope (meta.required_scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Denied permission, project folder access, or API-key scope (meta.required_scope)
\n"},"404":{"description":"Resource not found in the caller's organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Resource not found in the caller's organization
\n"},"4XX":{"description":"Client error returned in the public API envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Client error returned in the public API envelope
\n"}},"x-required-scope":"evals.delete","x-required-scopes":["evals.delete"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS -X DELETE \\\n \"$STACKAI_BASE_URL/v2/evals/datasets/${DATASET_ID}\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\""}],"x-gitbook-description-html":"Delete a dataset and its rows and experiments.
\nHow to use
\nDeleting a dataset cascades to its rows and experiments. Retain required results before removal and verify the dataset belongs to the intended project.
\nAuthentication and permissions
\nRequired permissions: evals.delete. Resource and owner access checks also apply.
First created dataset row URL
\n"}},"x-gitbook-description-html":"Successful Response
\n"},"400":{"description":"Invalid request or pagination cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Invalid request or pagination cursor
\n"},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Missing or invalid credentials
\n"},"403":{"description":"Denied permission, project folder access, or API-key scope (meta.required_scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Denied permission, project folder access, or API-key scope (meta.required_scope)
\n"},"404":{"description":"Resource not found in the caller's organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Resource not found in the caller's organization
\n"},"409":{"description":"Name conflict, concurrent operation, or dataset state prevents the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Name conflict, concurrent operation, or dataset state prevents the operation
\n"},"422":{"description":"Invalid evaluation contract, row shape, evaluator configuration, or filter combination","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Invalid evaluation contract, row shape, evaluator configuration, or filter combination
\n"},"4XX":{"description":"Client error returned in the public API envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Client error returned in the public API envelope
\n"}},"x-required-scope":"evals.update","x-required-scopes":["evals.update"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS \\\n \"$STACKAI_BASE_URL/v2/evals/datasets/${DATASET_ID}/rows\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\" \\\n -H 'Content-Type: application/json' \\\n --data-binary @request.json"}],"x-gitbook-description-html":"Append rows as given; Location is the first created row.
\nHow to use
\nAppend 1–100 rows with input keys matching the dataset contract. Include expected_output for reference-based evaluation. This appends as supplied; use imports when inputs/expected output should be extracted from real traces.
\nAuthentication and permissions
\nRequired permissions: evals.update. Resource and owner access checks also apply.
Prepare request.json
\nSave the example body below as request.json for the curl sample. Replace example IDs, node keys, and dynamic configuration with values for your organization; these are illustrative, not pre-existing resources.
{\n "rows": [\n {\n "inputs": {\n "in-0": "What is 2+2?"\n },\n "expected_output": {\n "out-0": "4"\n }\n }\n ]\n}\nNumber of items to skip.
\n"},"description":"Number of items to skip.","x-gitbook-description-html":"Number of items to skip.
\n"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum number of items to return.","default":50,"title":"Limit","x-gitbook-description-html":"Maximum number of items to return.
\n"},"description":"Maximum number of items to return.","x-gitbook-description-html":"Maximum number of items to return.
\n"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OffsetBasedPaginationResponse_EvalDatasetRowResponseV2_"}}},"x-gitbook-description-html":"Successful Response
\n"},"400":{"description":"Invalid request or pagination cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Invalid request or pagination cursor
\n"},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Missing or invalid credentials
\n"},"403":{"description":"Denied permission, project folder access, or API-key scope (meta.required_scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Denied permission, project folder access, or API-key scope (meta.required_scope)
\n"},"404":{"description":"Resource not found in the caller's organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Resource not found in the caller's organization
\n"},"4XX":{"description":"Client error returned in the public API envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Client error returned in the public API envelope
\n"}},"x-required-scope":"evals.read","x-required-scopes":["evals.read"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS \\\n \"$STACKAI_BASE_URL/v2/evals/datasets/${DATASET_ID}/rows\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\""}],"x-gitbook-description-html":"List dataset rows in position order.
\nHow to use
\nTraverse in position order with offset/limit. Use the parent dataset ID together with returned row IDs for updates or deletes.
\nAuthentication and permissions
\nRequired permissions: evals.read. Resource and owner access checks also apply.
First imported dataset row URL
\n"}},"x-gitbook-description-html":"Successful Response
\n"},"400":{"description":"Invalid request or pagination cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Invalid request or pagination cursor
\n"},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Missing or invalid credentials
\n"},"403":{"description":"Denied permission, project folder access, or API-key scope (meta.required_scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Denied permission, project folder access, or API-key scope (meta.required_scope)
\n"},"404":{"description":"Resource not found in the caller's organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Resource not found in the caller's organization
\n"},"409":{"description":"Name conflict, concurrent operation, or dataset state prevents the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Name conflict, concurrent operation, or dataset state prevents the operation
\n"},"422":{"description":"Invalid evaluation contract, row shape, evaluator configuration, or filter combination","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Invalid evaluation contract, row shape, evaluator configuration, or filter combination
\n"},"4XX":{"description":"Client error returned in the public API envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Client error returned in the public API envelope
\n"}},"x-required-scope":"evals.update","x-required-scopes":["evals.update","analytics.read"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS \\\n \"$STACKAI_BASE_URL/v2/evals/datasets/${DATASET_ID}/imports\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\" \\\n -H 'Content-Type: application/json' \\\n --data-binary @request.json"}],"x-gitbook-description-html":"Import finished runs atomically, requiring evals.update and analytics.read.
\nInputs and expected outputs come from each run trace under the dataset contract.\nA run without a usable trace rejects the whole batch; Location is the first row.
\nHow to use
\nImport 1–100 finished run IDs from the dataset project. Requires both evals.update and analytics.read. The whole batch is rejected if a trace is unusable; correct the identified runs before resubmission.
\nAuthentication and permissions
\nRequired permissions: evals.update, analytics.read. Resource and owner access checks also apply.
Prepare request.json
\nSave the example body below as request.json for the curl sample. Replace example IDs, node keys, and dynamic configuration with values for your organization; these are illustrative, not pre-existing resources.
{\n "run_ids": [\n "00000000-0000-4000-8000-000000000001"\n ]\n}\nSuccessful Response
\n"},"400":{"description":"Invalid request or pagination cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Invalid request or pagination cursor
\n"},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Missing or invalid credentials
\n"},"403":{"description":"Denied permission, project folder access, or API-key scope (meta.required_scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Denied permission, project folder access, or API-key scope (meta.required_scope)
\n"},"404":{"description":"Resource not found in the caller's organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Resource not found in the caller's organization
\n"},"4XX":{"description":"Client error returned in the public API envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Client error returned in the public API envelope
\n"}},"x-required-scope":"evals.read","x-required-scopes":["evals.read"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS \\\n \"$STACKAI_BASE_URL/v2/evals/datasets/${DATASET_ID}/rows/${ROW_ID}\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\""}],"x-gitbook-description-html":"Read one row after checking its dataset membership and project access.
\nHow to use
\nUse to inspect the exact input and expected-output pair before changing it. The row must belong to the dataset in the path.
\nAuthentication and permissions
\nRequired permissions: evals.read. Resource and owner access checks also apply.
Successful Response
\n"},"400":{"description":"Invalid request or pagination cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Invalid request or pagination cursor
\n"},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Missing or invalid credentials
\n"},"403":{"description":"Denied permission, project folder access, or API-key scope (meta.required_scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Denied permission, project folder access, or API-key scope (meta.required_scope)
\n"},"404":{"description":"Resource not found in the caller's organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Resource not found in the caller's organization
\n"},"422":{"description":"Invalid evaluation contract, row shape, evaluator configuration, or filter combination","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Invalid evaluation contract, row shape, evaluator configuration, or filter combination
\n"},"4XX":{"description":"Client error returned in the public API envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Client error returned in the public API envelope
\n"}},"x-required-scope":"evals.update","x-required-scopes":["evals.update"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS -X PATCH \\\n \"$STACKAI_BASE_URL/v2/evals/datasets/${DATASET_ID}/rows/${ROW_ID}\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\" \\\n -H 'Content-Type: application/json' \\\n --data-binary @request.json"}],"x-gitbook-description-html":"Update row content, allowing an explicit null to clear expected output.
\nHow to use
\nOmit expected_output to retain it; send explicit null to clear it. Keep input keys aligned to the parent dataset contract. Review the modified row before running experiments.
\nAuthentication and permissions
\nRequired permissions: evals.update. Resource and owner access checks also apply.
Prepare request.json
\nSave the example body below as request.json for the curl sample. Replace example IDs, node keys, and dynamic configuration with values for your organization; these are illustrative, not pre-existing resources.
{\n "expected_output": null\n}\nSuccessful Response
\n"},"400":{"description":"Invalid request or pagination cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Invalid request or pagination cursor
\n"},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Missing or invalid credentials
\n"},"403":{"description":"Denied permission, project folder access, or API-key scope (meta.required_scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Denied permission, project folder access, or API-key scope (meta.required_scope)
\n"},"404":{"description":"Resource not found in the caller's organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Resource not found in the caller's organization
\n"},"4XX":{"description":"Client error returned in the public API envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Client error returned in the public API envelope
\n"}},"x-required-scope":"evals.delete","x-required-scopes":["evals.delete"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS -X DELETE \\\n \"$STACKAI_BASE_URL/v2/evals/datasets/${DATASET_ID}/rows/${ROW_ID}\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\""}],"x-gitbook-description-html":"Delete one row belonging to the selected dataset.
\nHow to use
\nDelete one row from its parent dataset. Verify parent membership and preserve examples needed for future regression coverage.
\nAuthentication and permissions
\nRequired permissions: evals.delete. Resource and owner access checks also apply.
Case-insensitive name/description match
\n"},"description":"Case-insensitive name/description match","x-gitbook-description-html":"Case-insensitive name/description match
\n"},{"name":"compatible_with_dataset_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Keep only evaluators this dataset's contract can feed","title":"Compatible With Dataset Id","x-gitbook-description-html":"Keep only evaluators this dataset's contract can feed
\n"},"description":"Keep only evaluators this dataset's contract can feed","x-gitbook-description-html":"Keep only evaluators this dataset's contract can feed
\n"},{"name":"compatible_with_experiment_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Keep only evaluators this experiment's pinned contract can feed","title":"Compatible With Experiment Id","x-gitbook-description-html":"Keep only evaluators this experiment's pinned contract can feed
\n"},"description":"Keep only evaluators this experiment's pinned contract can feed","x-gitbook-description-html":"Keep only evaluators this experiment's pinned contract can feed
\n"},{"name":"exclude_evaluator_ids","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string","format":"uuid"}},{"type":"null"}],"description":"Evaluator ids to leave out; repeat the param","title":"Exclude Evaluator Ids","x-gitbook-description-html":"Evaluator ids to leave out; repeat the param
\n"},"description":"Evaluator ids to leave out; repeat the param","x-gitbook-description-html":"Evaluator ids to leave out; repeat the param
\n"},{"name":"uses_expected_output","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Keep only evaluators that do (true) or don't (false) compare against an expected output","title":"Uses Expected Output","x-gitbook-description-html":"Keep only evaluators that do (true) or don't (false) compare against an expected output
\n"},"description":"Keep only evaluators that do (true) or don't (false) compare against an expected output","x-gitbook-description-html":"Keep only evaluators that do (true) or don't (false) compare against an expected output
\n"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of items to skip.","default":0,"title":"Offset","x-gitbook-description-html":"Number of items to skip.
\n"},"description":"Number of items to skip.","x-gitbook-description-html":"Number of items to skip.
\n"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum number of items to return.","default":50,"title":"Limit","x-gitbook-description-html":"Maximum number of items to return.
\n"},"description":"Maximum number of items to return.","x-gitbook-description-html":"Maximum number of items to return.
\n"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OffsetBasedPaginationResponse_EvaluatorResponseV2_"}}},"x-gitbook-description-html":"Successful Response
\n"},"400":{"description":"Invalid request or pagination cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Invalid request or pagination cursor
\n"},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Missing or invalid credentials
\n"},"403":{"description":"Denied permission, project folder access, or API-key scope (meta.required_scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Denied permission, project folder access, or API-key scope (meta.required_scope)
\n"},"404":{"description":"Resource not found in the caller's organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Resource not found in the caller's organization
\n"},"422":{"description":"Invalid evaluation contract, row shape, evaluator configuration, or filter combination","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Invalid evaluation contract, row shape, evaluator configuration, or filter combination
\n"},"4XX":{"description":"Client error returned in the public API envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Client error returned in the public API envelope
\n"}},"x-required-scope":"evals.read","x-required-scopes":["evals.read"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS --get \\\n \"$STACKAI_BASE_URL/v2/evals/evaluators\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\" \\\n --data-urlencode \"project_id=${PROJECT_ID}\""}],"x-gitbook-description-html":"List project evaluators with optional compatibility and exclusion filters.
\nHow to use
\nSupply project_id. Filter by dataset/experiment compatibility, excluded IDs, or uses_expected_output. Monitors and direct run scoring require reference-free evaluators.
\nAuthentication and permissions
\nRequired permissions: evals.read. Resource and owner access checks also apply.
Created evaluator URL
\n"}},"x-gitbook-description-html":"Successful Response
\n"},"400":{"description":"Invalid request or pagination cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Invalid request or pagination cursor
\n"},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Missing or invalid credentials
\n"},"403":{"description":"Denied permission, project folder access, or API-key scope (meta.required_scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Denied permission, project folder access, or API-key scope (meta.required_scope)
\n"},"404":{"description":"Resource not found in the caller's organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Resource not found in the caller's organization
\n"},"409":{"description":"Name conflict, concurrent operation, or dataset state prevents the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Name conflict, concurrent operation, or dataset state prevents the operation
\n"},"422":{"description":"Invalid evaluation contract, row shape, evaluator configuration, or filter combination","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Invalid evaluation contract, row shape, evaluator configuration, or filter combination
\n"},"4XX":{"description":"Client error returned in the public API envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Client error returned in the public API envelope
\n"}},"x-required-scope":"evals.create","x-required-scopes":["evals.create"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS \\\n \"$STACKAI_BASE_URL/v2/evals/evaluators\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\" \\\n -H 'Content-Type: application/json' \\\n --data-binary @request.json"}],"x-gitbook-description-html":"Create a validated evaluator and its first immutable configuration version.
\nHow to use
\nChoose a built-in template or validate a judge configuration through preview first. Supply evaluator_type, config, and the project node contract. This creates the first immutable configuration version.
\nAuthentication and permissions
\nRequired permissions: evals.create. Resource and owner access checks also apply.
Prepare request.json
\nSave the example body below as request.json for the curl sample. Replace example IDs, node keys, and dynamic configuration with values for your organization; these are illustrative, not pre-existing resources.
{\n "project_id": "YOUR_PROJECT_ID",\n "name": "Correct request category",\n "evaluator_type": "builtin_rule",\n "config": {\n "rule": "exact_match",\n "target_output_node_id": "out-0"\n },\n "node_contract": {\n "input_kind": "legacy_input_nodes",\n "input_keys": [\n "in-0"\n ],\n "output_node_ids": [\n "out-0"\n ]\n }\n}\nSuccessful Response
\n"},"400":{"description":"Invalid request or pagination cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Invalid request or pagination cursor
\n"},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Missing or invalid credentials
\n"},"403":{"description":"Denied permission, project folder access, or API-key scope (meta.required_scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Denied permission, project folder access, or API-key scope (meta.required_scope)
\n"},"404":{"description":"Resource not found in the caller's organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Resource not found in the caller's organization
\n"},"4XX":{"description":"Client error returned in the public API envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Client error returned in the public API envelope
\n"}},"x-required-scope":"evals.read","x-required-scopes":["evals.read"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS \\\n \"$STACKAI_BASE_URL/v2/evals/evaluators/${EVALUATOR_ID}\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\""}],"x-gitbook-description-html":"Read an evaluator with its current version.
\nHow to use
\nRead the evaluator and its current configuration version before using its ID in an experiment or monitor. Verify whether it expects reference output.
\nAuthentication and permissions
\nRequired permissions: evals.read. Resource and owner access checks also apply.
Successful Response
\n"},"400":{"description":"Invalid request or pagination cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Invalid request or pagination cursor
\n"},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Missing or invalid credentials
\n"},"403":{"description":"Denied permission, project folder access, or API-key scope (meta.required_scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Denied permission, project folder access, or API-key scope (meta.required_scope)
\n"},"404":{"description":"Resource not found in the caller's organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Resource not found in the caller's organization
\n"},"409":{"description":"Name conflict, concurrent operation, or dataset state prevents the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Name conflict, concurrent operation, or dataset state prevents the operation
\n"},"422":{"description":"Invalid evaluation contract, row shape, evaluator configuration, or filter combination","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Invalid evaluation contract, row shape, evaluator configuration, or filter combination
\n"},"4XX":{"description":"Client error returned in the public API envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Client error returned in the public API envelope
\n"}},"x-required-scope":"evals.update","x-required-scopes":["evals.update"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS -X PATCH \\\n \"$STACKAI_BASE_URL/v2/evals/evaluators/${EVALUATOR_ID}\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\" \\\n -H 'Content-Type: application/json' \\\n --data-binary @request.json"}],"x-gitbook-description-html":"Update metadata and version material changes to judge configuration.
\nHow to use
\nUpdate metadata or judge configuration. Material config changes create a new immutable version; account for this when comparing historical scores.
\nAuthentication and permissions
\nRequired permissions: evals.update. Resource and owner access checks also apply.
Prepare request.json
\nSave the example body below as request.json for the curl sample. Replace example IDs, node keys, and dynamic configuration with values for your organization; these are illustrative, not pre-existing resources.
{\n "name": "Reviewed evaluator"\n}\nSuccessful Response
\n"},"400":{"description":"Invalid request or pagination cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Invalid request or pagination cursor
\n"},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Missing or invalid credentials
\n"},"403":{"description":"Denied permission, project folder access, or API-key scope (meta.required_scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Denied permission, project folder access, or API-key scope (meta.required_scope)
\n"},"404":{"description":"Resource not found in the caller's organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Resource not found in the caller's organization
\n"},"4XX":{"description":"Client error returned in the public API envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Client error returned in the public API envelope
\n"}},"x-required-scope":"evals.delete","x-required-scopes":["evals.delete"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS -X DELETE \\\n \"$STACKAI_BASE_URL/v2/evals/evaluators/${EVALUATOR_ID}\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\""}],"x-gitbook-description-html":"Soft-delete an evaluator while retaining its historical scores.
\nHow to use
\nSoft-delete an evaluator that should no longer be selected. Historical scores remain; deleting does not erase the prior evidence.
\nAuthentication and permissions
\nRequired permissions: evals.delete. Resource and owner access checks also apply.
Successful Response
\n"},"400":{"description":"Invalid request or pagination cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Invalid request or pagination cursor
\n"},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Missing or invalid credentials
\n"},"403":{"description":"Denied permission, project folder access, or API-key scope (meta.required_scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Denied permission, project folder access, or API-key scope (meta.required_scope)
\n"},"404":{"description":"Resource not found in the caller's organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Resource not found in the caller's organization
\n"},"422":{"description":"Invalid evaluation contract, row shape, evaluator configuration, or filter combination","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Invalid evaluation contract, row shape, evaluator configuration, or filter combination
\n"},"4XX":{"description":"Client error returned in the public API envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Client error returned in the public API envelope
\n"}},"security":[{"HTTPBearer":[]}],"x-required-scope":"evals.run","x-required-scopes":["evals.run"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS \\\n \"$STACKAI_BASE_URL/v2/evals/evaluator-previews\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\" \\\n -H 'Content-Type: application/json' \\\n --data-binary @request.json"}],"x-gitbook-description-html":"Judge up to three samples without saving the evaluator or score rows.
\nHow to use
\nTest 1–3 samples without saving an evaluator or score rows. Use this to check rubric/config behavior before production use. A preview may still consume judge resources; it is not a persistence operation.
\nAuthentication and permissions
\nRequired permissions: evals.run. Resource and owner access checks also apply.
Prepare request.json
\nSave the example body below as request.json for the curl sample. Replace example IDs, node keys, and dynamic configuration with values for your organization; these are illustrative, not pre-existing resources.
{\n "project_id": "YOUR_PROJECT_ID",\n "evaluator_type": "builtin_rule",\n "config": {\n "rule": "exact_match",\n "target_output_node_id": "out-0"\n },\n "samples": [\n {\n "generated_output": {\n "out-0": "billing"\n },\n "expected_output": {\n "out-0": "billing"\n }\n }\n ]\n}\nSuccessful Response
\n"},"400":{"description":"Invalid request or pagination cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Invalid request or pagination cursor
\n"},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Missing or invalid credentials
\n"},"403":{"description":"Denied permission, project folder access, or API-key scope (meta.required_scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Denied permission, project folder access, or API-key scope (meta.required_scope)
\n"},"4XX":{"description":"Client error returned in the public API envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Client error returned in the public API envelope
\n"}},"security":[{"HTTPBearer":[]}],"x-required-scope":"evals.read","x-required-scopes":["evals.read"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS \\\n \"$STACKAI_BASE_URL/v2/evals/evaluator-templates\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\""}],"x-gitbook-description-html":"Return built-in starting points for evaluator configuration.
\nHow to use
\nRead supported starting configurations instead of guessing arbitrary config fields. Adapt a template to the project contract and preview it with representative samples.
\nAuthentication and permissions
\nRequired permissions: evals.read. Resource and owner access checks also apply.
Case-insensitive name/description match
\n"},"description":"Case-insensitive name/description match","x-gitbook-description-html":"Case-insensitive name/description match
\n"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of items to skip.","default":0,"title":"Offset","x-gitbook-description-html":"Number of items to skip.
\n"},"description":"Number of items to skip.","x-gitbook-description-html":"Number of items to skip.
\n"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum number of items to return.","default":50,"title":"Limit","x-gitbook-description-html":"Maximum number of items to return.
\n"},"description":"Maximum number of items to return.","x-gitbook-description-html":"Maximum number of items to return.
\n"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OffsetBasedPaginationResponse_EvalExperimentSummaryResponseV2_"}}},"x-gitbook-description-html":"Successful Response
\n"},"400":{"description":"Invalid request or pagination cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Invalid request or pagination cursor
\n"},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Missing or invalid credentials
\n"},"403":{"description":"Denied permission, project folder access, or API-key scope (meta.required_scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Denied permission, project folder access, or API-key scope (meta.required_scope)
\n"},"404":{"description":"Resource not found in the caller's organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Resource not found in the caller's organization
\n"},"4XX":{"description":"Client error returned in the public API envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Client error returned in the public API envelope
\n"}},"x-required-scope":"evals.read","x-required-scopes":["evals.read"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS --get \\\n \"$STACKAI_BASE_URL/v2/evals/experiments\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\" \\\n --data-urlencode \"project_id=${PROJECT_ID}\""}],"x-gitbook-description-html":"List a project's experiments and their aggregate scores.
\nHow to use
\nSupply project_id and optionally dataset_id/search. Use aggregates to locate an experiment, then inspect detail and row-level results before comparing quality.
\nAuthentication and permissions
\nRequired permissions: evals.read. Resource and owner access checks also apply.
Created experiment URL
\n"}},"x-gitbook-description-html":"Successful Response
\n"},"400":{"description":"Invalid request or pagination cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Invalid request or pagination cursor
\n"},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Missing or invalid credentials
\n"},"403":{"description":"Denied permission, project folder access, or API-key scope (meta.required_scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Denied permission, project folder access, or API-key scope (meta.required_scope)
\n"},"404":{"description":"Resource not found in the caller's organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Resource not found in the caller's organization
\n"},"409":{"description":"Name conflict, concurrent operation, or dataset state prevents the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Name conflict, concurrent operation, or dataset state prevents the operation
\n"},"422":{"description":"Invalid evaluation contract, row shape, evaluator configuration, or filter combination","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Invalid evaluation contract, row shape, evaluator configuration, or filter combination
\n"},"4XX":{"description":"Client error returned in the public API envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Client error returned in the public API envelope
\n"}},"x-required-scope":"evals.create","x-required-scopes":["evals.create"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS \\\n \"$STACKAI_BASE_URL/v2/evals/experiments\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\" \\\n -H 'Content-Type: application/json' \\\n --data-binary @request.json"}],"x-gitbook-description-html":"Snapshot a dataset and validate the selected workflow version and evaluators.
\nHow to use
\nSnapshot an existing dataset with a selected saved workflow version or draft and compatible evaluators. This creates the experiment; execution starts separately through jobs.
\nAuthentication and permissions
\nRequired permissions: evals.create. Resource and owner access checks also apply.
Prepare request.json
\nSave the example body below as request.json for the curl sample. Replace example IDs, node keys, and dynamic configuration with values for your organization; these are illustrative, not pre-existing resources.
{\n "dataset_id": "00000000-0000-4000-8000-000000000001",\n "project_version_id": 1,\n "evaluator_ids": [\n "00000000-0000-4000-8000-000000000001"\n ]\n}\nSuccessful Response
\n"},"400":{"description":"Invalid request or pagination cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Invalid request or pagination cursor
\n"},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Missing or invalid credentials
\n"},"403":{"description":"Denied permission, project folder access, or API-key scope (meta.required_scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Denied permission, project folder access, or API-key scope (meta.required_scope)
\n"},"404":{"description":"Resource not found in the caller's organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Resource not found in the caller's organization
\n"},"503":{"description":"Job launch was rejected or job state is temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Job launch was rejected or job state is temporarily unavailable
\n"},"4XX":{"description":"Client error returned in the public API envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Client error returned in the public API envelope
\n"}},"x-required-scope":"evals.read","x-required-scopes":["evals.read"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS \\\n \"$STACKAI_BASE_URL/v2/evals/experiments/${EXPERIMENT_ID}\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\""}],"x-gitbook-description-html":"Get experiment metadata, progress, evaluator summaries and aggregate cards.
\nHow to use
\nRead the experiment snapshot metadata, progress and aggregate cards. Aggregate success can coexist with individual row failures; inspect the rows as well.
\nAuthentication and permissions
\nRequired permissions: evals.read. Resource and owner access checks also apply.
Successful Response
\n"},"400":{"description":"Invalid request or pagination cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Invalid request or pagination cursor
\n"},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Missing or invalid credentials
\n"},"403":{"description":"Denied permission, project folder access, or API-key scope (meta.required_scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Denied permission, project folder access, or API-key scope (meta.required_scope)
\n"},"404":{"description":"Resource not found in the caller's organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Resource not found in the caller's organization
\n"},"4XX":{"description":"Client error returned in the public API envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Client error returned in the public API envelope
\n"}},"x-required-scope":"evals.update","x-required-scopes":["evals.update"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS -X PATCH \\\n \"$STACKAI_BASE_URL/v2/evals/experiments/${EXPERIMENT_ID}\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\" \\\n -H 'Content-Type: application/json' \\\n --data-binary @request.json"}],"x-gitbook-description-html":"Update metadata; omitted fields remain unchanged and null clears notes.
\nHow to use
\nUpdate metadata only as permitted by the request schema. Omitted fields stay unchanged; null clears notes. This is not a replacement for creating a new experiment snapshot.
\nAuthentication and permissions
\nRequired permissions: evals.update. Resource and owner access checks also apply.
Prepare request.json
\nSave the example body below as request.json for the curl sample. Replace example IDs, node keys, and dynamic configuration with values for your organization; these are illustrative, not pre-existing resources.
{\n "notes": "Reviewed regression run"\n}\nSuccessful Response
\n"},"400":{"description":"Invalid request or pagination cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Invalid request or pagination cursor
\n"},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Missing or invalid credentials
\n"},"403":{"description":"Denied permission, project folder access, or API-key scope (meta.required_scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Denied permission, project folder access, or API-key scope (meta.required_scope)
\n"},"404":{"description":"Resource not found in the caller's organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Resource not found in the caller's organization
\n"},"4XX":{"description":"Client error returned in the public API envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Client error returned in the public API envelope
\n"}},"x-required-scope":"evals.delete","x-required-scopes":["evals.delete"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS -X DELETE \\\n \"$STACKAI_BASE_URL/v2/evals/experiments/${EXPERIMENT_ID}\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\""}],"x-gitbook-description-html":"Delete an experiment and its row snapshots and scores.
\nHow to use
\nDeletes the experiment with its row snapshots and scores. Export or record required results before removal.
\nAuthentication and permissions
\nRequired permissions: evals.delete. Resource and owner access checks also apply.
Number of items to skip.
\n"},"description":"Number of items to skip.","x-gitbook-description-html":"Number of items to skip.
\n"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum number of items to return.","default":50,"title":"Limit","x-gitbook-description-html":"Maximum number of items to return.
\n"},"description":"Maximum number of items to return.","x-gitbook-description-html":"Maximum number of items to return.
\n"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OffsetBasedPaginationResponse_EvalExperimentRowResponseV2_"}}},"x-gitbook-description-html":"Successful Response
\n"},"400":{"description":"Invalid request or pagination cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Invalid request or pagination cursor
\n"},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Missing or invalid credentials
\n"},"403":{"description":"Denied permission, project folder access, or API-key scope (meta.required_scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Denied permission, project folder access, or API-key scope (meta.required_scope)
\n"},"404":{"description":"Resource not found in the caller's organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Resource not found in the caller's organization
\n"},"503":{"description":"Job launch was rejected or job state is temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Job launch was rejected or job state is temporarily unavailable
\n"},"4XX":{"description":"Client error returned in the public API envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Client error returned in the public API envelope
\n"}},"x-required-scope":"evals.read","x-required-scopes":["evals.read"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS \\\n \"$STACKAI_BASE_URL/v2/evals/experiments/${EXPERIMENT_ID}/rows\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\""}],"x-gitbook-description-html":"Page the experiment's rows with every row's score payloads nested together.
\nHow to use
\nPage row snapshots with their nested score payloads. Inspect failures and score reasons; do not evaluate quality from aggregate metrics alone.
\nAuthentication and permissions
\nRequired permissions: evals.read. Resource and owner access checks also apply.
Successful Response
\n"},"400":{"description":"Invalid request or pagination cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Invalid request or pagination cursor
\n"},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Missing or invalid credentials
\n"},"403":{"description":"Denied permission, project folder access, or API-key scope (meta.required_scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Denied permission, project folder access, or API-key scope (meta.required_scope)
\n"},"404":{"description":"Resource not found in the caller's organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Resource not found in the caller's organization
\n"},"503":{"description":"Job launch was rejected or job state is temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Job launch was rejected or job state is temporarily unavailable
\n"},"4XX":{"description":"Client error returned in the public API envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Client error returned in the public API envelope
\n"}},"x-required-scope":"evals.read","x-required-scopes":["evals.read"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS \\\n \"$STACKAI_BASE_URL/v2/evals/experiments/${EXPERIMENT_ID}/status\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\""}],"x-gitbook-description-html":"Read the latest job and current result counts and aggregates.
\nHow to use
\nUse for latest-job overview and current counts/aggregates. For one accepted execution, poll its dedicated job URL so a later job does not change what you are observing.
\nAuthentication and permissions
\nRequired permissions: evals.read. Resource and owner access checks also apply.
Accepted job URL
\n"}},"x-gitbook-description-html":"Successful Response
\n"},"400":{"description":"Invalid request or pagination cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Invalid request or pagination cursor
\n"},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Missing or invalid credentials
\n"},"403":{"description":"Denied permission, project folder access, or API-key scope (meta.required_scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Denied permission, project folder access, or API-key scope (meta.required_scope)
\n"},"404":{"description":"Resource not found in the caller's organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Resource not found in the caller's organization
\n"},"409":{"headers":{"Location":{"description":"URL of the active job, when known","schema":{"type":"string"},"x-gitbook-description-html":"URL of the active job, when known
\n"}},"description":"The experiment already has an active job. When its identity is known, the error envelope includes meta.job_id, meta.experiment_id, meta.status_url and a matching Location header. Poll that job until it reaches a final status, then retry. Other conflicts omit this metadata and Location.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"The experiment already has an active job. When its identity is known, the error envelope includes meta.job_id, meta.experiment_id, meta.status_url and a matching Location header. Poll that job until it reaches a final status, then retry. Other conflicts omit this metadata and Location.
\n"},"422":{"description":"Invalid evaluation contract, row shape, evaluator configuration, or filter combination","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Invalid evaluation contract, row shape, evaluator configuration, or filter combination
\n"},"503":{"description":"Job launch was rejected or job state is temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Job launch was rejected or job state is temporarily unavailable
\n"},"4XX":{"description":"Client error returned in the public API envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Client error returned in the public API envelope
\n"}},"x-required-scope":"evals.run","x-required-scopes":["evals.run"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS \\\n \"$STACKAI_BASE_URL/v2/evals/experiments/${EXPERIMENT_ID}/jobs\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\" \\\n -H 'Content-Type: application/json' \\\n --data-binary @request.json"}],"x-gitbook-description-html":"Start a job on the experiment. With mode generate the job produces outputs for the experiment's rows and scores them in the same job when evaluator IDs are passed; with mode score it scores the existing outputs with the selected evaluators, at least one, and regenerates nothing. The job is queued: the response is 202 with the job URL in Location and status_url. Poll that URL until the job's status is completed, completed_with_failures, failed or cancelled. One job runs per experiment at a time; starting another while one is active returns 409. When the active job is known, Location and meta.status_url point to it, with its IDs in meta.job_id and meta.experiment_id.
How to use
\nUse generate for new outputs (and optional evaluation), score for existing outputs with at least one evaluator. Persist the returned job ID/status_url. Only one active job is allowed; follow the existing job on 409 instead of starting duplicates.
\nAuthentication and permissions
\nRequired permissions: evals.run. Resource and owner access checks also apply.
Prepare request.json
\nSave the example body below as request.json for the curl sample. Replace example IDs, node keys, and dynamic configuration with values for your organization; these are illustrative, not pre-existing resources.
{\n "mode": "generate",\n "evaluator_ids": [\n "00000000-0000-4000-8000-000000000001"\n ]\n}\nThe experiment the job belongs to.
\n"},"description":"The experiment the job belongs to.","x-gitbook-description-html":"The experiment the job belongs to.
\n"},{"name":"job_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The job ID returned when the job was created.","title":"Job Id","x-gitbook-description-html":"The job ID returned when the job was created.
\n"},"description":"The job ID returned when the job was created.","x-gitbook-description-html":"The job ID returned when the job was created.
\n"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIDataResponse_EvalExperimentJobResponseV2_"}}},"x-gitbook-description-html":"Successful Response
\n"},"400":{"description":"Invalid request or pagination cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Invalid request or pagination cursor
\n"},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Missing or invalid credentials
\n"},"403":{"description":"Denied permission, project folder access, or API-key scope (meta.required_scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Denied permission, project folder access, or API-key scope (meta.required_scope)
\n"},"404":{"description":"Resource not found in the caller's organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Resource not found in the caller's organization
\n"},"503":{"description":"Job launch was rejected or job state is temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Job launch was rejected or job state is temporarily unavailable
\n"},"4XX":{"description":"Client error returned in the public API envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Client error returned in the public API envelope
\n"}},"x-required-scope":"evals.read","x-required-scopes":["evals.read"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS \\\n \"$STACKAI_BASE_URL/v2/evals/experiments/${EXPERIMENT_ID}/jobs/${JOB_ID}\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\""}],"x-gitbook-description-html":"A job is one accepted request to generate outputs for an experiment or to score its existing outputs. This route returns the job's lifecycle and, once it has finished, its outcome. Poll it until status is completed, completed_with_failures, failed or cancelled. The experiment's /status route reports its latest job and current result counts. A 503 means the job's live state cannot be read right now; retry the same job URL.
How to use
\nPoll this exact accepted job until completed, completed_with_failures, failed, or cancelled. On 503 retry this GET. Inspect final outcome before deciding whether a new job is warranted.
\nAuthentication and permissions
\nRequired permissions: evals.read. Resource and owner access checks also apply.
Successful Response
\n"},"400":{"description":"Invalid request or pagination cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Invalid request or pagination cursor
\n"},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Missing or invalid credentials
\n"},"403":{"description":"Denied permission, project folder access, or API-key scope (meta.required_scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Denied permission, project folder access, or API-key scope (meta.required_scope)
\n"},"4XX":{"description":"Client error returned in the public API envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Client error returned in the public API envelope
\n"}},"security":[{"HTTPBearer":[]}],"x-required-scope":"evals.read","x-required-scopes":["evals.read"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS \\\n \"$STACKAI_BASE_URL/v2/evals/monitor-limits\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\""}],"x-gitbook-description-html":"Get server-enforced sampling limits and monitor defaults.
\nHow to use
\nRead enforced sampling limits and defaults before presenting a monitor-creation form. Do not permanently hard-code the policy in your client.
\nAuthentication and permissions
\nRequired permissions: evals.read. Resource and owner access checks also apply.
Case-insensitive name match
\n"},"description":"Case-insensitive name match","x-gitbook-description-html":"Case-insensitive name match
\n"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of items to skip.","default":0,"title":"Offset","x-gitbook-description-html":"Number of items to skip.
\n"},"description":"Number of items to skip.","x-gitbook-description-html":"Number of items to skip.
\n"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum number of items to return.","default":50,"title":"Limit","x-gitbook-description-html":"Maximum number of items to return.
\n"},"description":"Maximum number of items to return.","x-gitbook-description-html":"Maximum number of items to return.
\n"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OffsetBasedPaginationResponse_EvalMonitorListItemResponseV2_"}}},"x-gitbook-description-html":"Successful Response
\n"},"400":{"description":"Invalid request or pagination cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Invalid request or pagination cursor
\n"},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Missing or invalid credentials
\n"},"403":{"description":"Denied permission, project folder access, or API-key scope (meta.required_scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Denied permission, project folder access, or API-key scope (meta.required_scope)
\n"},"404":{"description":"Resource not found in the caller's organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Resource not found in the caller's organization
\n"},"4XX":{"description":"Client error returned in the public API envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Client error returned in the public API envelope
\n"}},"x-required-scope":"evals.read","x-required-scopes":["evals.read"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS --get \\\n \"$STACKAI_BASE_URL/v2/evals/monitors\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\" \\\n --data-urlencode \"project_id=${PROJECT_ID}\""}],"x-gitbook-description-html":"List project monitors with their seven-day score and alert rollups.
\nHow to use
\nSupply project_id and inspect seven-day score/alert rollups. Read individual monitor configuration before changing sampling or notification behavior.
\nAuthentication and permissions
\nRequired permissions: evals.read. Resource and owner access checks also apply.
Created monitor URL
\n"}},"x-gitbook-description-html":"Successful Response
\n"},"400":{"description":"Invalid request or pagination cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Invalid request or pagination cursor
\n"},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Missing or invalid credentials
\n"},"403":{"description":"Denied permission, project folder access, or API-key scope (meta.required_scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Denied permission, project folder access, or API-key scope (meta.required_scope)
\n"},"404":{"description":"Resource not found in the caller's organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Resource not found in the caller's organization
\n"},"409":{"description":"Name conflict, concurrent operation, or dataset state prevents the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Name conflict, concurrent operation, or dataset state prevents the operation
\n"},"422":{"description":"Invalid evaluation contract, row shape, evaluator configuration, or filter combination","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Invalid evaluation contract, row shape, evaluator configuration, or filter combination
\n"},"4XX":{"description":"Client error returned in the public API envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Client error returned in the public API envelope
\n"}},"x-required-scope":"evals.create","x-required-scopes":["evals.create"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS \\\n \"$STACKAI_BASE_URL/v2/evals/monitors\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\" \\\n -H 'Content-Type: application/json' \\\n --data-binary @request.json"}],"x-gitbook-description-html":"Create a monitor with one reference-free evaluator and bounded sampling.
\nHow to use
\nChoose one reference-free evaluator and bounded sampling. Read monitor-limits first; save the monitor ID and inspect statistics after representative production runs.
\nAuthentication and permissions
\nRequired permissions: evals.create. Resource and owner access checks also apply.
Prepare request.json
\nSave the example body below as request.json for the curl sample. Replace example IDs, node keys, and dynamic configuration with values for your organization; these are illustrative, not pre-existing resources.
{\n "project_id": "YOUR_PROJECT_ID",\n "evaluator_id": "00000000-0000-4000-8000-000000000001",\n "sampling_rate": 0.1,\n "max_runs_daily": 100\n}\nSuccessful Response
\n"},"400":{"description":"Invalid request or pagination cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Invalid request or pagination cursor
\n"},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Missing or invalid credentials
\n"},"403":{"description":"Denied permission, project folder access, or API-key scope (meta.required_scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Denied permission, project folder access, or API-key scope (meta.required_scope)
\n"},"404":{"description":"Resource not found in the caller's organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Resource not found in the caller's organization
\n"},"4XX":{"description":"Client error returned in the public API envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Client error returned in the public API envelope
\n"}},"x-required-scope":"evals.read","x-required-scopes":["evals.read"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS \\\n \"$STACKAI_BASE_URL/v2/evals/monitors/${MONITOR_ID}\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\""}],"x-gitbook-description-html":"Get one monitor's configuration and enabled state.
\nHow to use
\nRead the current configuration and enabled state before a partial update. A monitor is a sampling policy, not an evaluation of every run.
\nAuthentication and permissions
\nRequired permissions: evals.read. Resource and owner access checks also apply.
Successful Response
\n"},"400":{"description":"Invalid request or pagination cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Invalid request or pagination cursor
\n"},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Missing or invalid credentials
\n"},"403":{"description":"Denied permission, project folder access, or API-key scope (meta.required_scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Denied permission, project folder access, or API-key scope (meta.required_scope)
\n"},"404":{"description":"Resource not found in the caller's organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Resource not found in the caller's organization
\n"},"409":{"description":"Name conflict, concurrent operation, or dataset state prevents the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Name conflict, concurrent operation, or dataset state prevents the operation
\n"},"4XX":{"description":"Client error returned in the public API envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Client error returned in the public API envelope
\n"}},"x-required-scope":"evals.update","x-required-scopes":["evals.update"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS -X PATCH \\\n \"$STACKAI_BASE_URL/v2/evals/monitors/${MONITOR_ID}\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\" \\\n -H 'Content-Type: application/json' \\\n --data-binary @request.json"}],"x-gitbook-description-html":"Update selected monitor fields, retaining omitted settings.
\nHow to use
\nSend only settings to change and retain omitted values. Keep sampling within the current server limits; validate evaluator suitability when changing it.
\nAuthentication and permissions
\nRequired permissions: evals.update. Resource and owner access checks also apply.
Prepare request.json
\nSave the example body below as request.json for the curl sample. Replace example IDs, node keys, and dynamic configuration with values for your organization; these are illustrative, not pre-existing resources.
{\n "sampling_rate": 0.1\n}\nSuccessful Response
\n"},"400":{"description":"Invalid request or pagination cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Invalid request or pagination cursor
\n"},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Missing or invalid credentials
\n"},"403":{"description":"Denied permission, project folder access, or API-key scope (meta.required_scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Denied permission, project folder access, or API-key scope (meta.required_scope)
\n"},"404":{"description":"Resource not found in the caller's organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Resource not found in the caller's organization
\n"},"4XX":{"description":"Client error returned in the public API envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Client error returned in the public API envelope
\n"}},"x-required-scope":"evals.delete","x-required-scopes":["evals.delete"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS -X DELETE \\\n \"$STACKAI_BASE_URL/v2/evals/monitors/${MONITOR_ID}\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\""}],"x-gitbook-description-html":"Delete a monitor while retaining existing scores in run history.
\nHow to use
\nRemove the monitor while retaining existing scores in run history. This is not an erasure of historical run evaluations.
\nAuthentication and permissions
\nRequired permissions: evals.delete. Resource and owner access checks also apply.
Successful Response
\n"},"400":{"description":"Invalid request or pagination cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Invalid request or pagination cursor
\n"},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Missing or invalid credentials
\n"},"403":{"description":"Denied permission, project folder access, or API-key scope (meta.required_scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Denied permission, project folder access, or API-key scope (meta.required_scope)
\n"},"404":{"description":"Resource not found in the caller's organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Resource not found in the caller's organization
\n"},"4XX":{"description":"Client error returned in the public API envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Client error returned in the public API envelope
\n"}},"x-required-scope":"evals.read","x-required-scopes":["evals.read"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS \\\n \"$STACKAI_BASE_URL/v2/evals/monitors/${MONITOR_ID}/score-stats\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\""}],"x-gitbook-description-html":"Get windowed score trends and the monitor's current queue counters.
\nHow to use
\nChoose 24h, 7d, 30d, or all. Inspect both trends and queue counters; low score volume may reflect sampling or queued work rather than lack of runs.
\nAuthentication and permissions
\nRequired permissions: evals.read. Resource and owner access checks also apply.
Successful Response
\n"},"400":{"description":"Invalid request or pagination cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Invalid request or pagination cursor
\n"},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Missing or invalid credentials
\n"},"403":{"description":"Denied permission, project folder access, or API-key scope (meta.required_scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Denied permission, project folder access, or API-key scope (meta.required_scope)
\n"},"404":{"description":"Resource not found in the caller's organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Resource not found in the caller's organization
\n"},"4XX":{"description":"Client error returned in the public API envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Client error returned in the public API envelope
\n"}},"x-required-scope":"evals.read","x-required-scopes":["evals.read"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS \\\n \"$STACKAI_BASE_URL/v2/evals/monitors/${MONITOR_ID}/alert\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\""}],"x-gitbook-description-html":"Read stored alert knobs, severity and resolved server defaults.
\nHow to use
\nRead stored alert settings, current severity, and resolved defaults before tuning. Compare resolved values rather than assuming unset means disabled.
\nAuthentication and permissions
\nRequired permissions: evals.read. Resource and owner access checks also apply.
Successful Response
\n"},"400":{"description":"Invalid request or pagination cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Invalid request or pagination cursor
\n"},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Missing or invalid credentials
\n"},"403":{"description":"Denied permission, project folder access, or API-key scope (meta.required_scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Denied permission, project folder access, or API-key scope (meta.required_scope)
\n"},"404":{"description":"Resource not found in the caller's organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Resource not found in the caller's organization
\n"},"4XX":{"description":"Client error returned in the public API envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Client error returned in the public API envelope
\n"}},"x-required-scope":"evals.update","x-required-scopes":["evals.update"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS -X PATCH \\\n \"$STACKAI_BASE_URL/v2/evals/monitors/${MONITOR_ID}/alert\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\" \\\n -H 'Content-Type: application/json' \\\n --data-binary @request.json"}],"x-gitbook-description-html":"Tune alert settings; explicit null resets a knob to the server default.
\nHow to use
\nOmit a knob to retain it; set it to null to restore the server default. Read back resolved settings after updating to verify the intended alert behavior.
\nAuthentication and permissions
\nRequired permissions: evals.update. Resource and owner access checks also apply.
Prepare request.json
\nSave the example body below as request.json for the curl sample. Replace example IDs, node keys, and dynamic configuration with values for your organization; these are illustrative, not pre-existing resources.
{}\nOptional identifier for the page that should be returned. If it is not provided, the first page will be returned.
\n"},"description":"Optional identifier for the page that should be returned. If it is not provided, the first page will be returned.","x-gitbook-description-html":"Optional identifier for the page that should be returned. If it is not provided, the first page will be returned.
\n"},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"minimum":1,"description":"Number of items to be returned in the page.","default":50,"title":"Page Size","x-gitbook-description-html":"Number of items to be returned in the page.
\n"},"description":"Number of items to be returned in the page.","x-gitbook-description-html":"Number of items to be returned in the page.
\n"},{"name":"direction","in":"query","required":false,"schema":{"$ref":"#/components/schemas/PaginationDirection","description":"Direction for pagination: 'next' to advance through pages (older items), 'prev' to go back (newer items)","default":"next","x-gitbook-description-html":"Direction for pagination: 'next' to advance through pages (older items), 'prev' to go back (newer items)
\n"},"description":"Direction for pagination: 'next' to advance through pages (older items), 'prev' to go back (newer items)","x-gitbook-description-html":"Direction for pagination: 'next' to advance through pages (older items), 'prev' to go back (newer items)
\n"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CursorPaginatedResponse_EvalMonitorSampledRunResponseV2_"}}},"x-gitbook-description-html":"Successful Response
\n"},"400":{"description":"Invalid request or pagination cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Invalid request or pagination cursor
\n"},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Missing or invalid credentials
\n"},"403":{"description":"Denied permission, project folder access, or API-key scope (meta.required_scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Denied permission, project folder access, or API-key scope (meta.required_scope)
\n"},"404":{"description":"Resource not found in the caller's organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Resource not found in the caller's organization
\n"},"4XX":{"description":"Client error returned in the public API envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Client error returned in the public API envelope
\n"}},"x-required-scope":"evals.read","x-required-scopes":["evals.read","analytics.read"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS \\\n \"$STACKAI_BASE_URL/v2/evals/monitors/${MONITOR_ID}/sampled-runs\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\""}],"x-gitbook-description-html":"Page sampled runs and latest evaluator verdicts at the traversal's insertion cutoff.
\nHow to use
\nRequires analytics.read as well as evals.read. Follow the cursor with unchanged filters; traversal preserves an insertion cutoff. Inspect the latest verdict associated with each sampled run.
\nAuthentication and permissions
\nRequired permissions: evals.read, analytics.read. Resource and owner access checks also apply.
Created run score URL
\n"}},"x-gitbook-description-html":"Successful Response
\n"},"400":{"description":"Invalid request or pagination cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Invalid request or pagination cursor
\n"},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Missing or invalid credentials
\n"},"403":{"description":"Denied permission, project folder access, or API-key scope (meta.required_scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Denied permission, project folder access, or API-key scope (meta.required_scope)
\n"},"404":{"description":"Resource not found in the caller's organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Resource not found in the caller's organization
\n"},"422":{"description":"Invalid evaluation contract, row shape, evaluator configuration, or filter combination","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Invalid evaluation contract, row shape, evaluator configuration, or filter combination
\n"},"4XX":{"description":"Client error returned in the public API envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Client error returned in the public API envelope
\n"}},"x-required-scope":"evals.run","x-required-scopes":["evals.run","analytics.read"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS \\\n \"$STACKAI_BASE_URL/v2/evals/runs/${RUN_ID}/scores\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\" \\\n -H 'Content-Type: application/json' \\\n --data-binary @request.json"}],"x-gitbook-description-html":"Append one score by evaluating an existing run with a reference-free evaluator.
\nHow to use
\nEvaluate an existing run with a reference-free evaluator. Requires evals.run and analytics.read. Each call appends a score, so an ambiguous retry can add another history entry.
\nAuthentication and permissions
\nRequired permissions: evals.run, analytics.read. Resource and owner access checks also apply.
Prepare request.json
\nSave the example body below as request.json for the curl sample. Replace example IDs, node keys, and dynamic configuration with values for your organization; these are illustrative, not pre-existing resources.
{\n "evaluator_id": "00000000-0000-4000-8000-000000000001"\n}\nOptional identifier for the page that should be returned. If it is not provided, the first page will be returned.
\n"},"description":"Optional identifier for the page that should be returned. If it is not provided, the first page will be returned.","x-gitbook-description-html":"Optional identifier for the page that should be returned. If it is not provided, the first page will be returned.
\n"},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"minimum":1,"description":"Number of items to be returned in the page.","default":50,"title":"Page Size","x-gitbook-description-html":"Number of items to be returned in the page.
\n"},"description":"Number of items to be returned in the page.","x-gitbook-description-html":"Number of items to be returned in the page.
\n"},{"name":"direction","in":"query","required":false,"schema":{"$ref":"#/components/schemas/PaginationDirection","description":"Direction for pagination: 'next' to advance through pages (older items), 'prev' to go back (newer items)","default":"next","x-gitbook-description-html":"Direction for pagination: 'next' to advance through pages (older items), 'prev' to go back (newer items)
\n"},"description":"Direction for pagination: 'next' to advance through pages (older items), 'prev' to go back (newer items)","x-gitbook-description-html":"Direction for pagination: 'next' to advance through pages (older items), 'prev' to go back (newer items)
\n"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CursorPaginatedResponse_EvalRunScoreResponseV2_"}}},"x-gitbook-description-html":"Successful Response
\n"},"400":{"description":"Invalid request or pagination cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Invalid request or pagination cursor
\n"},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Missing or invalid credentials
\n"},"403":{"description":"Denied permission, project folder access, or API-key scope (meta.required_scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Denied permission, project folder access, or API-key scope (meta.required_scope)
\n"},"404":{"description":"Resource not found in the caller's organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Resource not found in the caller's organization
\n"},"4XX":{"description":"Client error returned in the public API envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Client error returned in the public API envelope
\n"}},"x-required-scope":"evals.read","x-required-scopes":["evals.read","analytics.read"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS \\\n \"$STACKAI_BASE_URL/v2/evals/runs/${RUN_ID}/scores\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\""}],"x-gitbook-description-html":"Page a run's append-only score history, oldest first.
\nHow to use
\nRead append-only score history oldest first. Requires analytics.read as well as evals.read. Follow cursors and compare evaluator versions before interpreting changed scores.
\nAuthentication and permissions
\nRequired permissions: evals.read, analytics.read. Resource and owner access checks also apply.
Successful Response
\n"},"400":{"description":"Invalid request or pagination cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Invalid request or pagination cursor
\n"},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Missing or invalid credentials
\n"},"403":{"description":"Denied permission, project folder access, or API-key scope (meta.required_scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Denied permission, project folder access, or API-key scope (meta.required_scope)
\n"},"404":{"description":"Resource not found in the caller's organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Resource not found in the caller's organization
\n"},"4XX":{"description":"Client error returned in the public API envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Client error returned in the public API envelope
\n"}},"x-required-scope":"evals.read","x-required-scopes":["evals.read","analytics.read"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS \\\n \"$STACKAI_BASE_URL/v2/evals/scores/${SCORE_ID}\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\""}],"x-gitbook-description-html":"Retrieve a retained run score by its unique score ID.
\nHow to use
\nRetrieve one retained score by score ID with evals.read and analytics.read. Use this to link an exact verdict in a review, rather than relying on the latest score.
\nAuthentication and permissions
\nRequired permissions: evals.read, analytics.read. Resource and owner access checks also apply.
Comma-separated list of statuses to filter by. Accepted values: PENDING, RUNNING, PAUSED, RESUMED, COMPLETED, FAILED, CANCELLED
\n"},"description":"Comma-separated list of statuses to filter by. Accepted values: PENDING, RUNNING, PAUSED, RESUMED, COMPLETED, FAILED, CANCELLED","x-gitbook-description-html":"Comma-separated list of statuses to filter by. Accepted values: PENDING, RUNNING, PAUSED, RESUMED, COMPLETED, FAILED, CANCELLED
\n"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ProjectRunSummary"},"title":"Response Getanalyticsdataapi"}}},"x-gitbook-description-html":"Successful Response
\n"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"x-gitbook-description-html":"Validation Error
\n"}},"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS \\\n \"$STACKAI_BASE_URL/analytics/org/${ORG_ID}/flows/${FLOW_ID}\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\""}],"x-gitbook-description-html":"List flow run logs matching the given filters.
\nHow to use
\nUse this for existing legacy exports. Read the response as a list. page starts at 0; dates should include a timezone. state uses uppercase legacy states and may contain comma-separated values. Use a personal key or legacy private organization key, not the legacy public key.
Authentication and permissions
\nAuthentication: personal API key or supported legacy private organization key in the Bearer header. This legacy route does not declare a separate endpoint permission scope in the checked contract.
\n"}},"/v2/providers":{"get":{"tags":["endpoint-listProvidersV2"],"summary":"List Providers","description":"List integration providers available in the public catalog.\n\n**How to use**\n\nUse the returned provider IDs to discover actions and triggers; do not guess slugs. Advance offset/limit to inspect the full catalog. Listing a provider does not authorize use of any connection.\n\n**Authentication and permissions**\n\nRequired permissions: `connections.read`. Resource and owner access checks also apply.","operationId":"listProvidersV2","security":[{"HTTPBearer":[]}],"parameters":[{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of items to skip","default":0,"title":"Offset","x-gitbook-description-html":"Number of items to skip
\n"},"description":"Number of items to skip","x-gitbook-description-html":"Number of items to skip
\n"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Number of items per page","default":50,"title":"Limit","x-gitbook-description-html":"Number of items per page
\n"},"description":"Number of items per page","x-gitbook-description-html":"Number of items per page
\n"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OffsetBasedPaginationResponse_ProviderResponseV2_"}}},"x-gitbook-description-html":"Successful Response
\n"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"x-gitbook-description-html":"Validation Error
\n"}},"x-required-scopes":["connections.read"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS \\\n \"$STACKAI_BASE_URL/v2/providers\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\""}],"x-gitbook-description-html":"List integration providers available in the public catalog.
\nHow to use
\nUse the returned provider IDs to discover actions and triggers; do not guess slugs. Advance offset/limit to inspect the full catalog. Listing a provider does not authorize use of any connection.
\nAuthentication and permissions
\nRequired permissions: connections.read. Resource and owner access checks also apply.
Successful Response
\n"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"x-gitbook-description-html":"Validation Error
\n"}},"x-required-scopes":["connections.read"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS \\\n \"$STACKAI_BASE_URL/v2/providers/${PROVIDER_ID}\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\""}],"x-gitbook-description-html":"Get a single provider from the public catalog by id.
\nHow to use
\nRead the descriptor for a provider selected from the catalog. Use its returned identifiers when fetching action and trigger collections.
\nAuthentication and permissions
\nRequired permissions: connections.read. Resource and owner access checks also apply.
Number of items to skip
\n"},"description":"Number of items to skip","x-gitbook-description-html":"Number of items to skip
\n"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Number of items per page","default":50,"title":"Limit","x-gitbook-description-html":"Number of items per page
\n"},"description":"Number of items per page","x-gitbook-description-html":"Number of items per page
\n"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OffsetBasedPaginationResponse_ProviderActionSummaryResponseV2_"}}},"x-gitbook-description-html":"Successful Response
\n"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"x-gitbook-description-html":"Validation Error
\n"}},"x-required-scopes":["connections.read"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS \\\n \"$STACKAI_BASE_URL/v2/providers/${PROVIDER_ID}/actions\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\""}],"x-gitbook-description-html":"List a provider's actions; fetch a single action for its input/output schema.
\nHow to use
\nChoose an action ID here, then fetch its detail before invoking it. List entries are for discovery and need not contain the full input/output contract.
\nAuthentication and permissions
\nRequired permissions: connections.read. Resource and owner access checks also apply.
Successful Response
\n"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"x-gitbook-description-html":"Validation Error
\n"}},"x-required-scopes":["connections.read"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS \\\n \"$STACKAI_BASE_URL/v2/providers/${PROVIDER_ID}/actions/${ACTION_ID}\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\""}],"x-gitbook-description-html":"Get a provider action, including its input and output parameters.
\nHow to use
\nUse the action-specific input and output parameter definitions to build inputs. Required fields, connection needs, and runtime behavior differ by action; there is no universal action payload.
\nAuthentication and permissions
\nRequired permissions: connections.read. Resource and owner access checks also apply.
Number of items to skip
\n"},"description":"Number of items to skip","x-gitbook-description-html":"Number of items to skip
\n"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Number of items per page","default":50,"title":"Limit","x-gitbook-description-html":"Number of items per page
\n"},"description":"Number of items per page","x-gitbook-description-html":"Number of items per page
\n"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OffsetBasedPaginationResponse_ProviderTriggerSummaryResponseV2_"}}},"x-gitbook-description-html":"Successful Response
\n"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"x-gitbook-description-html":"Validation Error
\n"}},"x-required-scopes":["connections.read"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS \\\n \"$STACKAI_BASE_URL/v2/providers/${PROVIDER_ID}/triggers\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\""}],"x-gitbook-description-html":"List a provider's triggers; fetch a single trigger for its parameter schema.
\nHow to use
\nDiscover the event sources an integration supports. Listing does not register, activate, or subscribe a workflow to a trigger.
\nAuthentication and permissions
\nRequired permissions: connections.read. Resource and owner access checks also apply.
Successful Response
\n"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"x-gitbook-description-html":"Validation Error
\n"}},"x-required-scopes":["connections.read"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS \\\n \"$STACKAI_BASE_URL/v2/providers/${PROVIDER_ID}/triggers/${TRIGGER_ID}\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\""}],"x-gitbook-description-html":"Get a provider trigger, including its input and output parameters.
\nHow to use
\nRead the trigger-specific parameter contract for configuration in the supported workflow interface. This endpoint only reads a descriptor.
\nAuthentication and permissions
\nRequired permissions: connections.read. Resource and owner access checks also apply.
Successful Response
\n"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"x-gitbook-description-html":"Validation Error
\n"}},"x-required-scopes":["connections.use"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS \\\n \"$STACKAI_BASE_URL/v2/providers/${PROVIDER_ID}/actions/${ACTION_ID}/run\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\" \\\n -H 'Content-Type: application/json' \\\n --data-binary @request.json"}],"x-gitbook-description-html":"Run a provider action synchronously and return its outputs.
\nHow to use
\nSelect a compatible accessible connection and submit inputs matching this action. Omit connection_id only when supported by that action. This synchronous call can change a third-party system; do not automatically repeat an ambiguous write.
\nAuthentication and permissions
\nRequired permissions: connections.use. Resource and owner access checks also apply.
Prepare request.json
\nSave the example body below as request.json for the curl sample. Replace example IDs, node keys, and dynamic configuration with values for your organization; these are illustrative, not pre-existing resources.
{\n "connection_id": "00000000-0000-4000-8000-000000000001",\n "inputs": {\n "ACTION_SPECIFIC_FIELD": "VALUE"\n }\n}\nFilter by provider id
\n"},"description":"Filter by provider id","x-gitbook-description-html":"Filter by provider id
\n"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of items to skip","default":0,"title":"Offset","x-gitbook-description-html":"Number of items to skip
\n"},"description":"Number of items to skip","x-gitbook-description-html":"Number of items to skip
\n"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Number of items per page","default":50,"title":"Limit","x-gitbook-description-html":"Number of items per page
\n"},"description":"Number of items per page","x-gitbook-description-html":"Number of items per page
\n"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OffsetBasedPaginationResponse_ConnectionResponseV2_"}}},"x-gitbook-description-html":"Successful Response
\n"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"x-gitbook-description-html":"Validation Error
\n"}},"x-required-scopes":["connections.read"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS \\\n \"$STACKAI_BASE_URL/v2/connections\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\""}],"x-gitbook-description-html":"List connections visible to the caller in their organization.
\nVisibility follows RBAC: a non-admin sees connections they created, shared with them\n(directly or via a group), or carrying an org-level role; an admin sees the whole\norganization. Degraded connections (rehydration failed) are included with\nstatus="needs_reconnection", not dropped.
How to use
\nFilter by a catalog provider_id and select a connection you may use. Non-admin results are access-filtered; missing entries may be unshared. needs_reconnection means repair is needed. This API has no connection-create route.
\nAuthentication and permissions
\nRequired permissions: connections.read. Resource and owner access checks also apply.
Successful Response
\n"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"x-gitbook-description-html":"Validation Error
\n"}},"x-required-scopes":["org.webhooks.manage"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS \\\n \"$STACKAI_BASE_URL/v2/webhooks/subscriptions\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\" \\\n -H 'Content-Type: application/json' \\\n --data-binary @request.json"}],"x-gitbook-description-html":"Register a webhook endpoint and return its signing secret.
\nThe secret is returned only here. It cannot be recovered later, so a caller that loses it\nhas to delete the subscription and create a new one.
\nHow to use
\nConfigure and test an HTTPS receiver first. Capture the returned signing secret immediately; it is returned only at creation. Use an authorized administrator session for org.webhooks.manage, which is not an assignable restricted API-key scope. Verify event emission in your deployment before relying on callbacks.
\nAuthentication and permissions
\nRequired permissions: org.webhooks.manage. Resource and owner access checks also apply.
Prepare request.json
\nSave the example body below as request.json for the curl sample. Replace example IDs, node keys, and dynamic configuration with values for your organization; these are illustrative, not pre-existing resources.
{\n "url": "https://your-service.example.com/webhooks/stackai",\n "event_types": [\n "run.succeeded",\n "run.failed"\n ]\n}\nNumber of items to skip
\n"},"description":"Number of items to skip","x-gitbook-description-html":"Number of items to skip
\n"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Number of items per page","default":50,"title":"Limit","x-gitbook-description-html":"Number of items per page
\n"},"description":"Number of items per page","x-gitbook-description-html":"Number of items per page
\n"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OffsetBasedPaginationResponse_WebhookSubscriptionResponseV2_"}}},"x-gitbook-description-html":"Successful Response
\n"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"x-gitbook-description-html":"Validation Error
\n"}},"x-required-scopes":["org.webhooks.manage"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS \\\n \"$STACKAI_BASE_URL/v2/webhooks/subscriptions\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\""}],"x-gitbook-description-html":"List the organization's active webhook subscriptions, oldest first.
\nHow to use
\nInventory active subscriptions oldest first using offset/limit. The signing secret is not recoverable here. Subscription existence does not prove your runtime emits every accepted event type.
\nAuthentication and permissions
\nRequired permissions: org.webhooks.manage. Resource and owner access checks also apply.
Successful Response
\n"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"x-gitbook-description-html":"Validation Error
\n"}},"x-required-scopes":["org.webhooks.manage"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS -X DELETE \\\n \"$STACKAI_BASE_URL/v2/webhooks/subscriptions/${SUBSCRIPTION_ID}\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\""}],"x-gitbook-description-html":"Delete a webhook subscription: deliveries stop and it leaves the list.
\nHow to use
\nUse the subscription ID returned by create/list. Deleting stops deliveries and removes it from active listing. To change a URL or replace a lost secret, create a replacement and retire the old subscription; no PATCH route is defined.
\nAuthentication and permissions
\nRequired permissions: org.webhooks.manage. Resource and owner access checks also apply.
Run created. Execution is asynchronous; poll the Location URL for progress.
\n"},"400":{"description":"Invalid request body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Invalid request body.
\n"},"401":{"description":"Authentication required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Authentication required.
\n"},"402":{"description":"Organization usage limit reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Organization usage limit reached.
\n"},"403":{"description":"Project run permission or credential scope required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"},"example":{"detail":["The credential does not have the required permission."],"meta":{"required_scope":"projects.run"}}}},"x-gitbook-description-html":"Project run permission or credential scope required.
\n"},"404":{"description":"Project or requested project version not found, project not published, or run logging disabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Project or requested project version not found, project not published, or run logging disabled.
\n"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"x-gitbook-description-html":"Validation Error
\n"},"500":{"description":"Run start or response retrieval failed; execution may already have started.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Run start or response retrieval failed; execution may already have started.
\n"},"503":{"description":"Run reservation failed; execution was not dispatched.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Run reservation failed; execution was not dispatched.
\n"}},"x-required-scopes":["projects.run"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS \\\n \"$STACKAI_BASE_URL/v2/runs\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\" \\\n -H 'Content-Type: application/json' \\\n --data-binary @request.json"}],"x-gitbook-description-html":"Start a run of a project version and return its current persisted state.
\nHow to use
\nSend project_id and singular input. A 201 creates a run but does not mean it succeeded. Persist data.run_id, then poll with analytics.read. Omitted/null project_version selects published, -1 selects draft, and a nonnegative integer pins a snapshot. A 500 can occur after execution starts; reconcile instead of automatically retrying.
Authentication and permissions
\nRequired permissions: projects.run. Resource and owner access checks also apply.
Prepare request.json
\nSave the example body below as request.json for the curl sample. Replace example IDs, node keys, and dynamic configuration with values for your organization; these are illustrative, not pre-existing resources.
{\n "project_id": "YOUR_PROJECT_ID",\n "input": {\n "in-0": "Summarize our refund policy"\n },\n "project_version": 1\n}\nOnly return runs of this project.
\n"},"description":"Only return runs of this project.","x-gitbook-description-html":"Only return runs of this project.
\n"},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/RunStatusV2"},{"type":"null"}],"title":"status","description":"Only return runs currently in this status.","x-gitbook-description-html":"Only return runs currently in this status.
\n"},"description":"Only return runs currently in this status.","x-gitbook-description-html":"Only return runs currently in this status.
\n"},{"name":"run_type","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/RunTypeV2"},{"type":"null"}],"title":"run_type","description":"Only return runs started this way. `unknown` is not filterable because it represents an unpublished value.","x-gitbook-description-html":"Only return runs started this way. unknown is not filterable because it represents an unpublished value.
Only return runs started this way. unknown is not filterable because it represents an unpublished value.
Filter by the exact created_by.id returned on a run: a user ID, organization ID, or end-user ID. Personal API-key runs use the owner's user ID.
\n"},"description":"Filter by the exact created_by.id returned on a run: a user ID, organization ID, or end-user ID. Personal API-key runs use the owner's user ID.","x-gitbook-description-html":"Filter by the exact created_by.id returned on a run: a user ID, organization ID, or end-user ID. Personal API-key runs use the owner's user ID.
\n"},{"name":"created_at__gte","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"created_at__gte","description":"Only return runs created at or after this time.","x-gitbook-description-html":"Only return runs created at or after this time.
\n"},"description":"Only return runs created at or after this time.","x-gitbook-description-html":"Only return runs created at or after this time.
\n"},{"name":"created_at__lte","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"created_at__lte","description":"Only return runs created at or before this time.","x-gitbook-description-html":"Only return runs created at or before this time.
\n"},"description":"Only return runs created at or before this time.","x-gitbook-description-html":"Only return runs created at or before this time.
\n"},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Opaque identifier for the page to return, taken from a previous response's `next_cursor`. Omit it to read the first page.","title":"Cursor","x-gitbook-description-html":"Opaque identifier for the page to return, taken from a previous response's next_cursor. Omit it to read the first page.
Opaque identifier for the page to return, taken from a previous response's next_cursor. Omit it to read the first page.
Number of runs to return in the page.
\n"},"description":"Number of runs to return in the page.","x-gitbook-description-html":"Number of runs to return in the page.
\n"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CursorPaginatedResponse_RunSummaryResponseV2_"}}},"x-gitbook-description-html":"Successful Response
\n"},"400":{"description":"Invalid cursor or filter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Invalid cursor or filter.
\n"},"401":{"description":"Authentication required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Authentication required.
\n"},"403":{"description":"Analytics read permission required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Analytics read permission required.
\n"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"x-gitbook-description-html":"Validation Error
\n"}},"x-required-scopes":["analytics.read"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS \\\n \"$STACKAI_BASE_URL/v2/runs\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\""}],"x-gitbook-description-html":"List runs in accessible projects newest first.
\nHow to use
\nUse this for run history or reconciliation. Follow next_cursor with unchanged filters. created_by_id is the exact returned actor ID; personal-key runs use the owner ID. Status filters use lowercase v2 values.
\nAuthentication and permissions
\nRequired permissions: analytics.read. Resource and owner access checks also apply.
Successful Response
\n"},"400":{"description":"Invalid run ID.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Invalid run ID.
\n"},"401":{"description":"Authentication required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Authentication required.
\n"},"403":{"description":"Analytics read permission required or run logging disabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"},"example":{"detail":["The credential does not have the required permission."],"meta":{"required_scope":"analytics.read"}}}},"x-gitbook-description-html":"Analytics read permission required or run logging disabled.
\n"},"404":{"description":"Run not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Run not found.
\n"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"x-gitbook-description-html":"Validation Error
\n"}},"x-required-scopes":["analytics.read"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS \\\n \"$STACKAI_BASE_URL/v2/runs/${RUN_ID}\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\""}],"x-gitbook-description-html":"Get one of the organization's runs with its full payload.
\nHow to use
\nPoll this after creation and inspect data.status. A 200 response can describe a failed run. The input/output may be null, and logging controls can block detail reads. pending_input is only exposed when the caller can both read and resume the run.
\nAuthentication and permissions
\nRequired permissions: analytics.read. Resource and owner access checks also apply.
Cancellation accepted. Poll the Location URL for the current run state.
\n"},"400":{"description":"Invalid run ID.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Invalid run ID.
\n"},"401":{"description":"Authentication required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Authentication required.
\n"},"403":{"description":"Project run permission or credential scope required, or run logging disabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Project run permission or credential scope required, or run logging disabled.
\n"},"404":{"description":"Run not found, inaccessible, or not owned by the authenticated actor.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Run not found, inaccessible, or not owned by the authenticated actor.
\n"},"409":{"description":"Run is no longer cancellable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Run is no longer cancellable.
\n"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"x-gitbook-description-html":"Validation Error
\n"},"500":{"description":"Cancellation signalling failed; the request may already have changed run state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Cancellation signalling failed; the request may already have changed run state.
\n"}},"x-required-scopes":["projects.run"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS -X POST \\\n \"$STACKAI_BASE_URL/v2/runs/${RUN_ID}/cancel\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\""}],"x-gitbook-description-html":"Request cancellation of an accessible run owned by this authenticated actor.
\nOwnership matches the actor type and identity that started the run, including\nthe distinction between a personal API key and a platform session. Acceptance\nacknowledges the request; it does not guarantee execution has already stopped.\nPolling the Location URL separately requires analytics read permission.
\nHow to use
\nUse the originating actor type and identity. A 202 acknowledges cancellation signalling, not a stopped execution; poll afterward. A 404 can indicate nonownership. Side effects already performed cannot be undone by cancellation.
\nAuthentication and permissions
\nRequired permissions: projects.run. Resource and owner access checks also apply.
Resume accepted. Poll the Location URL for the current run state.
\n"},"400":{"description":"Invalid or expired resume token, run ID or request body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Invalid or expired resume token, run ID or request body.
\n"},"401":{"description":"Authentication required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Authentication required.
\n"},"402":{"description":"Organization usage limit reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Organization usage limit reached.
\n"},"403":{"description":"Project run permission or credential scope required, or run logging disabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Project run permission or credential scope required, or run logging disabled.
\n"},"404":{"description":"Run not found or inaccessible.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Run not found or inaccessible.
\n"},"409":{"description":"Run is not resumable or requires an unsupported pause or backend.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Run is not resumable or requires an unsupported pause or backend.
\n"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"x-gitbook-description-html":"Validation Error
\n"},"500":{"description":"Resume failed; usage may already have been charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Resume failed; usage may already have been charged.
\n"}},"x-required-scopes":["projects.run"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS \\\n \"$STACKAI_BASE_URL/v2/runs/${RUN_ID}/resume\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\" \\\n -H 'Content-Type: application/json' \\\n --data-binary @request.json"}],"x-gitbook-description-html":"Accept an asynchronous response to a paused ask-human step.
\nHow to use
\nGET the paused run first, handle the human response, and send the issued resume token. Poll after 202. A 409 means state or pause/backend support is incompatible. On 500, usage may already have been charged; read current state before retrying.
\nAuthentication and permissions
\nRequired permissions: projects.run. Resource and owner access checks also apply.
Prepare request.json
\nSave the example body below as request.json for the curl sample. Replace example IDs, node keys, and dynamic configuration with values for your organization; these are illustrative, not pre-existing resources.
{\n "resume_token": "TOKEN_FROM_PENDING_INPUT",\n "response": "THE_HUMAN_ANSWER",\n "response_type": "text"\n}\nNumber of items to skip.
\n"},"description":"Number of items to skip.","x-gitbook-description-html":"Number of items to skip.
\n"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum number of items to return.","default":50,"title":"Limit","x-gitbook-description-html":"Maximum number of items to return.
\n"},"description":"Maximum number of items to return.","x-gitbook-description-html":"Maximum number of items to return.
\n"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OffsetBasedPaginationResponse_SkillListItemResponseV2_"}}},"x-gitbook-description-html":"Successful Response
\n"},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Invalid request parameters
\n"},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Authentication required
\n"},"403":{"description":"Permission denied; insufficient API-key scope includes meta.required_scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Permission denied; insufficient API-key scope includes meta.required_scope
\n"},"4XX":{"description":"Other client errors use the same public error envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Other client errors use the same public error envelope
\n"}},"x-required-scope":"skills.read","x-required-scopes":["skills.read"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS \\\n \"$STACKAI_BASE_URL/v2/skills\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\""}],"x-gitbook-description-html":"List visible skills, with builtins first followed by organization skills.
\nHow to use
\nBrowse built-in skills first, followed by visible organization skills. Save the skill ID and fetch a pinned version when reproducibility matters.
\nAuthentication and permissions
\nRequired permissions: skills.read. Resource and owner access checks also apply.
URL of the created resource
\n"}},"x-gitbook-description-html":"Created
\n"},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Invalid request parameters
\n"},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Authentication required
\n"},"403":{"description":"Permission denied; insufficient API-key scope includes meta.required_scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Permission denied; insufficient API-key scope includes meta.required_scope
\n"},"409":{"description":"Name or version conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Name or version conflict
\n"},"422":{"description":"Invalid skill bundle, including oversized uploads","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Invalid skill bundle, including oversized uploads
\n"},"500":{"description":"Skill persistence failed; internal details are not exposed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Skill persistence failed; internal details are not exposed
\n"},"4XX":{"description":"Other client errors use the same public error envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Other client errors use the same public error envelope
\n"}},"x-required-scope":"skills.create","x-required-scopes":["skills.create"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS \\\n \"$STACKAI_BASE_URL/v2/skills\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\" \\\n -F 'files=@skill.zip'"}],"x-gitbook-description-html":"Create and publish the first version from a multipart bundle or form fields.
\nHow to use
\nPublish the first version using multipart form fields or bundle files. Use files (plural), repeat parts for multiple files, preserve relative paths, or upload a zip. Save the created skill ID and version. A name conflict is 409; invalid/oversized bundles are 422.
\nAuthentication and permissions
\nRequired permissions: skills.create. Resource and owner access checks also apply.
ID of the skill.
\n"},"description":"ID of the skill.","x-gitbook-description-html":"ID of the skill.
\n"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIDataResponse_SkillResponseV2_"}}},"x-gitbook-description-html":"Successful Response
\n"},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Invalid request parameters
\n"},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Authentication required
\n"},"403":{"description":"Permission denied; insufficient API-key scope includes meta.required_scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Permission denied; insufficient API-key scope includes meta.required_scope
\n"},"404":{"description":"Skill or version not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Skill or version not found
\n"},"4XX":{"description":"Other client errors use the same public error envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Other client errors use the same public error envelope
\n"}},"x-required-scope":"skills.read","x-required-scopes":["skills.read"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS \\\n \"$STACKAI_BASE_URL/v2/skills/${SKILL_ID}\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\""}],"x-gitbook-description-html":"Retrieve the latest published skill and its public file manifest.
\nHow to use
\nRead the current published instructions and public file manifest. Latest can change; use the version endpoint for an integration pinned to reviewed instructions.
\nAuthentication and permissions
\nRequired permissions: skills.read. Resource and owner access checks also apply.
ID of the skill.
\n"},"description":"ID of the skill.","x-gitbook-description-html":"ID of the skill.
\n"}],"responses":{"204":{"description":"Successful Response","x-gitbook-description-html":"Successful Response
\n"},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Invalid request parameters
\n"},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Authentication required
\n"},"403":{"description":"Permission denied; insufficient API-key scope includes meta.required_scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Permission denied; insufficient API-key scope includes meta.required_scope
\n"},"404":{"description":"Skill or version not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Skill or version not found
\n"},"4XX":{"description":"Other client errors use the same public error envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Other client errors use the same public error envelope
\n"}},"x-required-scope":"skills.delete","x-required-scopes":["skills.delete"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS -X DELETE \\\n \"$STACKAI_BASE_URL/v2/skills/${SKILL_ID}\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\""}],"x-gitbook-description-html":"Delete an owned skill and all versions; organization admins may delete any org skill.
\nHow to use
\nThis removes the skill and all versions. It is not a single-version unpublish. Ownership is required unless an organization administrator is deleting an organization skill.
\nAuthentication and permissions
\nRequired permissions: skills.delete. Resource and owner access checks also apply.
ID of the skill.
\n"},"description":"ID of the skill.","x-gitbook-description-html":"ID of the skill.
\n"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of items to skip.","default":0,"title":"Offset","x-gitbook-description-html":"Number of items to skip.
\n"},"description":"Number of items to skip.","x-gitbook-description-html":"Number of items to skip.
\n"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum number of items to return.","default":50,"title":"Limit","x-gitbook-description-html":"Maximum number of items to return.
\n"},"description":"Maximum number of items to return.","x-gitbook-description-html":"Maximum number of items to return.
\n"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OffsetBasedPaginationResponse_SkillVersionListItemResponseV2_"}}},"x-gitbook-description-html":"Successful Response
\n"},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Invalid request parameters
\n"},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Authentication required
\n"},"403":{"description":"Permission denied; insufficient API-key scope includes meta.required_scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Permission denied; insufficient API-key scope includes meta.required_scope
\n"},"404":{"description":"Skill or version not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Skill or version not found
\n"},"4XX":{"description":"Other client errors use the same public error envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Other client errors use the same public error envelope
\n"}},"x-required-scope":"skills.read","x-required-scopes":["skills.read"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS \\\n \"$STACKAI_BASE_URL/v2/skills/${SKILL_ID}/versions\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\""}],"x-gitbook-description-html":"Page through a skill's version history, newest first.
\nHow to use
\nList newest versions first with offset pagination. Choose an explicit version for an auditable release or rollback decision.
\nAuthentication and permissions
\nRequired permissions: skills.read. Resource and owner access checks also apply.
ID of the skill.
\n"},"description":"ID of the skill.","x-gitbook-description-html":"ID of the skill.
\n"}],"requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_createSkillVersionV2"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIDataResponse_SkillVersionResponseV2_"}}},"headers":{"Location":{"description":"URL of the created resource","schema":{"type":"string"},"x-gitbook-description-html":"URL of the created resource
\n"}},"x-gitbook-description-html":"Created
\n"},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Invalid request parameters
\n"},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Authentication required
\n"},"403":{"description":"Permission denied; insufficient API-key scope includes meta.required_scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Permission denied; insufficient API-key scope includes meta.required_scope
\n"},"404":{"description":"Skill or version not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Skill or version not found
\n"},"409":{"description":"Name or version conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Name or version conflict
\n"},"422":{"description":"Invalid skill bundle, including oversized uploads","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Invalid skill bundle, including oversized uploads
\n"},"500":{"description":"Skill persistence failed; internal details are not exposed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Skill persistence failed; internal details are not exposed
\n"},"4XX":{"description":"Other client errors use the same public error envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Other client errors use the same public error envelope
\n"}},"x-required-scope":"skills.update","x-required-scopes":["skills.update"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS \\\n \"$STACKAI_BASE_URL/v2/skills/${SKILL_ID}/versions\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\" \\\n -F 'files=@skill.zip'"}],"x-gitbook-description-html":"Publish a new version, optionally carrying files from a previous version.
\nHow to use
\nPublish a new revision. Repeat carry_paths for files to keep; base_version selects the source version (current by default). Supplying a different name can rename the skill. Review the assembled bundle before publishing.
\nAuthentication and permissions
\nRequired permissions: skills.update. Resource and owner access checks also apply.
ID of the skill.
\n"},"description":"ID of the skill.","x-gitbook-description-html":"ID of the skill.
\n"},{"name":"version","in":"path","required":true,"schema":{"type":"integer","minimum":1,"description":"Skill version number (1-based).","title":"Version","x-gitbook-description-html":"Skill version number (1-based).
\n"},"description":"Skill version number (1-based).","x-gitbook-description-html":"Skill version number (1-based).
\n"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIDataResponse_SkillVersionResponseV2_"}}},"x-gitbook-description-html":"Successful Response
\n"},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Invalid request parameters
\n"},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Authentication required
\n"},"403":{"description":"Permission denied; insufficient API-key scope includes meta.required_scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Permission denied; insufficient API-key scope includes meta.required_scope
\n"},"404":{"description":"Skill or version not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Skill or version not found
\n"},"4XX":{"description":"Other client errors use the same public error envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackAIAPIErrorResponse"}}},"x-gitbook-description-html":"Other client errors use the same public error envelope
\n"}},"x-required-scope":"skills.read","x-required-scopes":["skills.read"],"x-hideTryItPanel":false,"x-codeSamples":[{"lang":"cURL","label":"curl","source":"curl --fail-with-body -sS \\\n \"$STACKAI_BASE_URL/v2/skills/${SKILL_ID}/versions/${VERSION}\" \\\n -H \"Authorization: Bearer $STACKAI_API_KEY\""}],"x-gitbook-description-html":"Retrieve one published version's instructions and public file manifest.
\nHow to use
\nFetch the exact 1-based version number. The response includes instructions and a public file manifest; retain this version alongside the consuming workflow configuration.
\nAuthentication and permissions
\nRequired permissions: skills.read. Resource and owner access checks also apply.
Bundle files; each part's filename is its relative POSIX path inside the bundle (optionally under one shared root folder). A single .zip is accepted as an alternative.
\n"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Skill name (form mode); a changed name renames the skill when published.","x-gitbook-description-html":"Skill name (form mode); a changed name renames the skill when published.
\n"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Skill description (form mode)."},"instructions":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Instructions","description":"SKILL.md body (form mode).","x-gitbook-description-html":"SKILL.md body (form mode).
\n"},"actions":{"items":{"type":"string"},"type":"array","title":"Actions","description":"Action refs; repeat the field per item.","x-gitbook-description-html":"Action refs; repeat the field per item.
\n"}},"type":"object","title":"Body_createSkillV2"},"Body_createSkillVersionV2":{"properties":{"files":{"items":{"type":"string","format":"binary"},"type":"array","title":"Files","description":"Bundle files; each part's filename is its relative POSIX path inside the bundle (optionally under one shared root folder). A single .zip is accepted as an alternative.","x-gitbook-description-html":"Bundle files; each part's filename is its relative POSIX path inside the bundle (optionally under one shared root folder). A single .zip is accepted as an alternative.
\n"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Skill name (form mode); a changed name renames the skill when published.","x-gitbook-description-html":"Skill name (form mode); a changed name renames the skill when published.
\n"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Skill description (form mode)."},"instructions":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Instructions","description":"SKILL.md body (form mode).","x-gitbook-description-html":"SKILL.md body (form mode).
\n"},"actions":{"items":{"type":"string"},"type":"array","title":"Actions","description":"Action refs; repeat the field per item.","x-gitbook-description-html":"Action refs; repeat the field per item.
\n"},"carry_paths":{"items":{"type":"string"},"type":"array","title":"Carry Paths","description":"File paths to carry over unchanged from the current files; repeat the field per item.","x-gitbook-description-html":"File paths to carry over unchanged from the current files; repeat the field per item.
\n"},"base_version":{"anyOf":[{"type":"integer","minimum":1},{"type":"null"}],"title":"Base Version","description":"Version to copy carry_paths from; defaults to the current version.","x-gitbook-description-html":"Version to copy carry_paths from; defaults to the current version.
\n"}},"type":"object","title":"Body_createSkillVersionV2"},"Body_uploadKnowledgeBaseResource":{"properties":{"file":{"type":"string","format":"binary","title":"File","description":"The file to upload to the knowledge base","x-gitbook-description-html":"The file to upload to the knowledge base
\n"}},"type":"object","required":["file"],"title":"Body_uploadKnowledgeBaseResource"},"Body_uploadKnowledgeBaseResourceV2":{"properties":{"file":{"type":"string","format":"binary","title":"File","description":"The file to upload to the knowledge base","x-gitbook-description-html":"The file to upload to the knowledge base
\n"}},"type":"object","required":["file"],"title":"Body_uploadKnowledgeBaseResourceV2"},"BooleanProperty":{"properties":{"type":{"type":"string","const":"boolean","title":"Type","default":"boolean"},"description":{"type":"string","maxLength":1024,"title":"Description","default":""},"order":{"type":"integer","minimum":0,"title":"Order","description":"Display order of this property within the schema.","default":0,"x-gitbook-description-html":"Display order of this property within the schema.
\n"}},"type":"object","title":"BooleanProperty"},"CacheMeasurement":{"properties":{"version":{"type":"integer","const":1,"title":"Version","default":1},"read_input_tokens":{"type":"integer","minimum":0,"title":"Read Input Tokens"},"observed_input_tokens":{"type":"integer","minimum":0,"title":"Observed Input Tokens"}},"type":"object","required":["read_input_tokens","observed_input_tokens"],"title":"CacheMeasurement","description":"A measured subset of provider input, excluding unobserved calls.","x-gitbook-description-html":"A measured subset of provider input, excluding unobserved calls.
\n"},"CacheMetrics":{"properties":{"read_input_tokens":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"title":"Read Input Tokens"},"observed_input_tokens":{"type":"integer","minimum":0,"title":"Observed Input Tokens","default":0},"known_input_tokens":{"type":"integer","minimum":0,"title":"Known Input Tokens","default":0},"missing_input_usage_records":{"type":"integer","minimum":0,"title":"Missing Input Usage Records","default":0},"cached_input_percent":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Cached Input Percent","description":"Return cache-read share for precisely the measured subset.","readOnly":true,"x-gitbook-description-html":"Return cache-read share for precisely the measured subset.
\n"},"input_coverage_percent":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Input Coverage Percent","description":"Return observed share of recorded input, not provider-attempt coverage.","readOnly":true,"x-gitbook-description-html":"Return observed share of recorded input, not provider-attempt coverage.
\n"}},"type":"object","required":["cached_input_percent","input_coverage_percent"],"title":"CacheMetrics","description":"Weighted cache reads over measured input, including writes but excluding output.","x-gitbook-description-html":"Weighted cache reads over measured input, including writes but excluding output.
\n"},"ChunkerType":{"type":"string","enum":["naive","sentence"],"title":"ChunkerType"},"ConnectionResponseV2":{"properties":{"connection_id":{"type":"string","format":"uuid","title":"Connection Id"},"provider_id":{"type":"string","title":"Provider Id"},"auth_method":{"type":"string","title":"Auth Method"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"status":{"$ref":"#/components/schemas/ConnectionStatusV2"},"expires_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Expires At"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["connection_id","provider_id","auth_method","name","status","expires_at","created_at","updated_at"],"title":"ConnectionResponse","description":"A connection on the public v2 surface, deliberately credential-free.","x-gitbook-description-html":"A connection on the public v2 surface, deliberately credential-free.
\n"},"ConnectionStatusV2":{"type":"string","enum":["active","needs_reconnection"],"title":"ConnectionStatusV2","description":"Public connection status: healthy vs. needing a reconnect.","x-gitbook-description-html":"Public connection status: healthy vs. needing a reconnect.
\n"},"CreateKnowledgeBaseEmbeddingParams":{"properties":{"embedding_model":{"type":"string","title":"Embedding Model","default":"openai.text-embedding-3-small"},"api_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}},"additionalProperties":false,"type":"object","title":"CreateKnowledgeBaseEmbeddingParams","description":"Embedding configuration for a new knowledge base.","x-gitbook-description-html":"Embedding configuration for a new knowledge base.
\n"},"CreateKnowledgeBaseRequest":{"properties":{"connection_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Connection Id"},"connection_source_ids":{"items":{"type":"string"},"type":"array","uniqueItems":true,"title":"Connection Source Ids"},"website_sources":{"items":{"$ref":"#/components/schemas/SelectedWebsiteSource"},"type":"array","title":"Website Sources"},"source_file_authorization_enabled":{"type":"boolean","title":"Source File Authorization Enabled","default":false},"name":{"type":"string","maxLength":2048,"minLength":1,"title":"Name","default":"Unnamed Knowledge Base"},"description":{"type":"string","maxLength":2048,"title":"Description","default":""},"indexing_params":{"$ref":"#/components/schemas/KnowledgeBaseIndexingParamsRequest"},"org_level_role":{"anyOf":[{"$ref":"#/components/schemas/KnowledgeBaseRole"},{"type":"null"}]}},"additionalProperties":false,"type":"object","title":"CreateKnowledgeBaseRequest","description":"Payload to create a new knowledge base.","x-gitbook-description-html":"Payload to create a new knowledge base.
\n"},"CreateKnowledgeBaseRequestV2":{"properties":{"connection_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Connection Id"},"connection_source_ids":{"items":{"type":"string"},"type":"array","uniqueItems":true,"title":"Connection Source Ids"},"website_sources":{"items":{"$ref":"#/components/schemas/SelectedWebsiteSource"},"type":"array","title":"Website Sources"},"source_file_authorization_enabled":{"type":"boolean","title":"Source File Authorization Enabled","default":false},"name":{"type":"string","maxLength":2048,"minLength":1,"title":"Name","default":"Unnamed Knowledge Base"},"description":{"type":"string","maxLength":2048,"title":"Description","default":""},"indexing_params":{"$ref":"#/components/schemas/KnowledgeBaseIndexingParamsRequest"},"org_level_role":{"anyOf":[{"$ref":"#/components/schemas/KnowledgeBaseRole"},{"type":"null"}]}},"additionalProperties":false,"type":"object","title":"CreateKnowledgeBaseRequest","description":"Payload to create a new knowledge base.","x-gitbook-description-html":"Payload to create a new knowledge base.
\n"},"CreateWebhookSubscriptionRequestV2":{"properties":{"url":{"type":"string","title":"Url","description":"The HTTPS endpoint that receives the signed event payloads.","x-gitbook-description-html":"The HTTPS endpoint that receives the signed event payloads.
\n"},"event_types":{"items":{"$ref":"#/components/schemas/WebhookEventType"},"type":"array","title":"Event Types","description":"Event types this subscription receives, for example `run.succeeded`.","x-gitbook-description-html":"Event types this subscription receives, for example run.succeeded.
A new webhook subscription on the public v2 surface.
\n"},"CursorPaginatedResponse_EvalMonitorSampledRunResponseV2_":{"properties":{"response_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Response Code","description":"Machine-readable response code, when provided.","x-gitbook-description-html":"Machine-readable response code, when provided.
\n"},"meta":{"additionalProperties":true,"type":"object","title":"Meta","description":"Additional metadata","default":{},"x-gitbook-description-html":"Additional metadata
\n"},"data":{"items":{"$ref":"#/components/schemas/EvalMonitorSampledRunResponseV2"},"type":"array","title":"Data"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor"},"prev_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prev Cursor"},"current_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Current Cursor"}},"type":"object","title":"CursorPaginatedResponse[EvalMonitorSampledRunResponseV2]"},"CursorPaginatedResponse_EvalRunScoreResponseV2_":{"properties":{"response_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Response Code","description":"Machine-readable response code, when provided.","x-gitbook-description-html":"Machine-readable response code, when provided.
\n"},"meta":{"additionalProperties":true,"type":"object","title":"Meta","description":"Additional metadata","default":{},"x-gitbook-description-html":"Additional metadata
\n"},"data":{"items":{"$ref":"#/components/schemas/EvalRunScoreResponseV2"},"type":"array","title":"Data"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor"},"prev_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prev Cursor"},"current_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Current Cursor"}},"type":"object","title":"CursorPaginatedResponse[EvalRunScoreResponseV2]"},"CursorPaginatedResponse_KnowledgeBaseFileResponseV2_":{"properties":{"response_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Response Code","description":"Machine-readable response code, when provided.","x-gitbook-description-html":"Machine-readable response code, when provided.
\n"},"meta":{"additionalProperties":true,"type":"object","title":"Meta","description":"Additional metadata","default":{},"x-gitbook-description-html":"Additional metadata
\n"},"data":{"items":{"$ref":"#/components/schemas/KnowledgeBaseFileResponseV2"},"type":"array","title":"Data"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor"},"prev_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prev Cursor"},"current_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Current Cursor"}},"type":"object","title":"CursorPaginatedResponse[KnowledgeBaseFileResponseV2]"},"CursorPaginatedResponse_KnowledgeBaseResponseV2_":{"properties":{"response_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Response Code","description":"Machine-readable response code, when provided.","x-gitbook-description-html":"Machine-readable response code, when provided.
\n"},"meta":{"additionalProperties":true,"type":"object","title":"Meta","description":"Additional metadata","default":{},"x-gitbook-description-html":"Additional metadata
\n"},"data":{"items":{"$ref":"#/components/schemas/KnowledgeBaseResponseV2"},"type":"array","title":"Data"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor"},"prev_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prev Cursor"},"current_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Current Cursor"}},"type":"object","title":"CursorPaginatedResponse[KnowledgeBaseResponseV2]"},"CursorPaginatedResponse_RunSummaryResponseV2_":{"properties":{"response_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Response Code","description":"Machine-readable response code, when provided.","x-gitbook-description-html":"Machine-readable response code, when provided.
\n"},"meta":{"additionalProperties":true,"type":"object","title":"Meta","description":"Additional metadata","default":{},"x-gitbook-description-html":"Additional metadata
\n"},"data":{"items":{"$ref":"#/components/schemas/RunSummaryResponseV2"},"type":"array","title":"Data"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor"},"prev_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prev Cursor"},"current_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Current Cursor"}},"type":"object","title":"CursorPaginatedResponse[RunSummaryResponseV2]"},"DateProperty":{"properties":{"type":{"type":"string","const":"date","title":"Type","default":"date"},"description":{"type":"string","maxLength":1024,"title":"Description","default":""},"order":{"type":"integer","minimum":0,"title":"Order","description":"Display order of this property within the schema.","default":0,"x-gitbook-description-html":"Display order of this property within the schema.
\n"}},"type":"object","title":"DateProperty"},"DeploymentStage":{"type":"string","enum":["draft","development","staging","production"],"title":"DeploymentStage","description":"Stages a workflow passes through before production.","x-gitbook-description-html":"Stages a workflow passes through before production.
\n"},"EvalAlertEffectiveConfigResponseV2":{"properties":{"threshold":{"type":"number","title":"Threshold"},"warning_threshold":{"type":"number","title":"Warning Threshold"},"min_samples":{"type":"integer","title":"Min Samples"},"window_max_runs":{"type":"integer","title":"Window Max Runs"},"window_hours":{"type":"integer","title":"Window Hours"},"min_effect_size":{"type":"number","title":"Min Effect Size"},"recovery_threshold":{"type":"number","title":"Recovery Threshold"},"renotify_hours":{"type":"integer","title":"Renotify Hours"}},"type":"object","required":["threshold","warning_threshold","min_samples","window_max_runs","window_hours","min_effect_size","recovery_threshold","renotify_hours"],"title":"EvalAlertEffectiveConfig"},"EvalAlertSeverity":{"type":"string","enum":["unknown","ok","warning","alert"],"title":"EvalAlertSeverity","description":"Per-(monitor, evaluator) alert state; notifications fire on transitions, not levels.","x-gitbook-description-html":"Per-(monitor, evaluator) alert state; notifications fire on transitions, not levels.
\n"},"EvalChoiceSegmentResponseV2":{"properties":{"label":{"type":"string","title":"Label"},"count":{"type":"integer","title":"Count"},"value":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Value"}},"type":"object","required":["label","count","value"],"title":"EvalChoiceSegment"},"EvalDatasetCreateRequestV2":{"properties":{"project_id":{"type":"string","minLength":1,"title":"Project Id"},"name":{"type":"string","maxLength":200,"minLength":1,"title":"Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"node_contract":{"$ref":"#/components/schemas/EvalNodeContractRequestV2"}},"additionalProperties":false,"type":"object","required":["project_id","name","node_contract"],"title":"EvalDatasetCreateRequest"},"EvalDatasetImportRequestV2":{"properties":{"run_ids":{"items":{"type":"string","format":"uuid"},"type":"array","maxItems":100,"minItems":1,"title":"Run Ids","description":"Finished runs of the dataset's project to import as rows: inputs and expected output are extracted from each run trace under the dataset contract and source_run_id is set. Any run without a usable trace rejects the whole batch with a 422 naming it. Requires evals.update and analytics.read.","x-gitbook-description-html":"Finished runs of the dataset's project to import as rows: inputs and expected output are extracted from each run trace under the dataset contract and source_run_id is set. Any run without a usable trace rejects the whole batch with a 422 naming it. Requires evals.update and analytics.read.
\n"}},"additionalProperties":false,"type":"object","required":["run_ids"],"title":"EvalDatasetImportRequest","examples":[{"run_ids":["6f1d2c3b-4a5e-4f60-8b7c-9d0e1f2a3b4c"]}]},"EvalDatasetListItemResponseV2":{"properties":{"dataset_id":{"type":"string","format":"uuid","title":"Dataset Id"},"project_id":{"type":"string","title":"Project Id"},"name":{"type":"string","title":"Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"node_contract":{"$ref":"#/components/schemas/EvalNodeContractV2"},"max_rows":{"type":"integer","title":"Max Rows"},"created_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Created By"},"updated_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Updated By"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["dataset_id","project_id","name","description","node_contract","max_rows","created_by","updated_by","created_at","updated_at"],"title":"EvalDatasetListItem"},"EvalDatasetResponseV2":{"properties":{"dataset_id":{"type":"string","format":"uuid","title":"Dataset Id"},"project_id":{"type":"string","title":"Project Id"},"name":{"type":"string","title":"Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"node_contract":{"$ref":"#/components/schemas/EvalNodeContractV2"},"max_rows":{"type":"integer","title":"Max Rows"},"created_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Created By"},"updated_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Updated By"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"},"warnings":{"items":{"type":"string"},"type":"array","title":"Warnings"}},"type":"object","required":["dataset_id","project_id","name","description","node_contract","max_rows","created_by","updated_by","created_at","updated_at"],"title":"EvalDataset"},"EvalDatasetRowDraftRequestV2":{"properties":{"inputs":{"additionalProperties":true,"type":"object","title":"Inputs"},"expected_output":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Expected Output"},"source_run_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Source Run Id"}},"additionalProperties":false,"type":"object","required":["inputs"],"title":"EvalDatasetRowDraftRequest"},"EvalDatasetRowResponseV2":{"properties":{"dataset_row_id":{"type":"string","format":"uuid","title":"Dataset Row Id"},"dataset_id":{"type":"string","format":"uuid","title":"Dataset Id"},"url":{"type":"string","title":"Url"},"position":{"type":"integer","title":"Position"},"inputs":{"additionalProperties":true,"type":"object","title":"Inputs"},"expected_output":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Expected Output"},"source_run_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Source Run Id"},"created_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Created By"},"updated_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Updated By"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["dataset_row_id","dataset_id","url","position","inputs","expected_output","source_run_id","created_by","updated_by","created_at","updated_at"],"title":"EvalDatasetRow"},"EvalDatasetRowUpdateRequestV2":{"properties":{"inputs":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Inputs","description":"Replacement input object. Omit or send null to keep the current inputs.","x-gitbook-description-html":"Replacement input object. Omit or send null to keep the current inputs.
\n"},"expected_output":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Expected Output","description":"Replacement expected output. Omit to keep the current value; send null or an empty object to clear it to null. Example: `{\"expected_output\": null}`.","x-gitbook-description-html":"Replacement expected output. Omit to keep the current value; send null or an empty object to clear it to null. Example: {"expected_output": null}.
Rows to append as given. Use the dataset imports endpoint for run traces.
\n"}},"additionalProperties":false,"type":"object","required":["rows"],"title":"EvalDatasetRowsAddRequest","examples":[{"rows":[{"expected_output":{"out-0":"4"},"inputs":{"in-0":"What is 2+2?"}}]}]},"EvalDatasetUpdateRequestV2":{"properties":{"name":{"anyOf":[{"type":"string","maxLength":200,"minLength":1},{"type":"null"}],"title":"Name","description":"New name. Omit or send null to keep the current name.","x-gitbook-description-html":"New name. Omit or send null to keep the current name.
\n"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"New description. Omit to keep the current description; send null to clear it. Example: `{\"description\": null}`."},"node_contract":{"anyOf":[{"$ref":"#/components/schemas/EvalNodeContractRequestV2"},{"type":"null"}],"description":"Replacement contract. Omit or send null to keep the current contract. Renaming input or output keys also renames those keys in existing dataset rows in the same atomic update.","x-gitbook-description-html":"Replacement contract. Omit or send null to keep the current contract. Renaming input or output keys also renames those keys in existing dataset rows in the same atomic update.
\n"}},"additionalProperties":false,"type":"object","title":"EvalDatasetUpdateRequest","examples":[{"name":"Renamed dataset"},{"node_contract":{"input_keys":["new-input"],"input_kind":"legacy_input_nodes","output_node_ids":["new-output"]}}]},"EvalExperimentAggregateCardResponseV2":{"properties":{"evaluator_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Evaluator Id"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"aggregate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Aggregate"},"scored_count":{"type":"integer","title":"Scored Count"},"judge_failed_count":{"type":"integer","title":"Judge Failed Count"},"has_scores":{"type":"boolean","title":"Has Scores"},"segments":{"anyOf":[{"items":{"$ref":"#/components/schemas/EvalExperimentChoiceSegmentResponseV2"},"type":"array"},{"type":"null"}],"title":"Segments"}},"type":"object","required":["evaluator_id","name","aggregate","scored_count","judge_failed_count","has_scores","segments"],"title":"EvalExperimentAggregateCard"},"EvalExperimentAggregateResponseV2":{"properties":{"evaluator_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Evaluator Id"},"evaluator_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Evaluator Name"},"score_kind":{"$ref":"#/components/schemas/EvalScoreKind"},"aggregate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Aggregate"},"scored_count":{"type":"integer","title":"Scored Count"},"judge_failed_count":{"type":"integer","title":"Judge Failed Count"},"choice_counts":{"anyOf":[{"additionalProperties":{"type":"integer"},"type":"object"},{"type":"null"}],"title":"Choice Counts"}},"type":"object","required":["evaluator_id","evaluator_name","score_kind","aggregate","scored_count","judge_failed_count","choice_counts"],"title":"EvalExperimentAggregate"},"EvalExperimentChoiceSegmentResponseV2":{"properties":{"label":{"type":"string","title":"Label"},"count":{"type":"integer","title":"Count"},"value":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Value"}},"type":"object","required":["label","count","value"],"title":"EvalExperimentChoiceSegment"},"EvalExperimentCreateRequestV2":{"properties":{"dataset_id":{"type":"string","format":"uuid","title":"Dataset Id"},"project_version_id":{"anyOf":[{"type":"string","const":"draft"},{"type":"integer","minimum":0}],"title":"Project Version Id"},"evaluator_ids":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Evaluator Ids"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"notes":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Notes"}},"additionalProperties":false,"type":"object","required":["dataset_id","project_version_id"],"title":"EvalExperimentCreateRequest"},"EvalExperimentCreateResponseV2":{"properties":{"experiment":{"$ref":"#/components/schemas/EvalExperimentResponseV2"},"warnings":{"$ref":"#/components/schemas/EvalExperimentWarningsResponseV2"}},"type":"object","required":["experiment","warnings"],"title":"EvalExperimentCreateResponseV2"},"EvalExperimentDetailResponseV2":{"properties":{"experiment":{"$ref":"#/components/schemas/EvalExperimentResponseV2"},"latest_job":{"anyOf":[{"$ref":"#/components/schemas/EvalExperimentJobResponseV2"},{"type":"null"}]},"job_status_available":{"type":"boolean","title":"Job Status Available"},"status_counts":{"$ref":"#/components/schemas/EvalExperimentStatusCountsResponseV2"},"aggregate_cards":{"items":{"$ref":"#/components/schemas/EvalExperimentAggregateCardResponseV2"},"type":"array","title":"Aggregate Cards"},"evaluators":{"items":{"$ref":"#/components/schemas/EvaluatorResponseV2"},"type":"array","title":"Evaluators"},"run_stats":{"$ref":"#/components/schemas/EvalExperimentRunStatsResponseV2"}},"type":"object","required":["experiment","latest_job","job_status_available","status_counts","aggregate_cards","evaluators","run_stats"],"title":"EvalExperimentDetail"},"EvalExperimentJobAcceptedResponseV2":{"properties":{"status":{"type":"string","const":"accepted","title":"Status","description":"The request was accepted. Poll the job for its current state.","default":"accepted","x-gitbook-description-html":"The request was accepted. Poll the job for its current state.
\n"},"job_id":{"type":"string","format":"uuid","title":"Job Id","description":"ID of the job that was created. Poll the job route with it.","x-gitbook-description-html":"ID of the job that was created. Poll the job route with it.
\n"},"experiment_id":{"type":"string","format":"uuid","title":"Experiment Id","description":"The experiment the job works on.","x-gitbook-description-html":"The experiment the job works on.
\n"},"status_url":{"type":"string","title":"Status Url","description":"Relative URL of the job, the same value as the Location header. Poll it until the job reaches a final status.","x-gitbook-description-html":"Relative URL of the job, the same value as the Location header. Poll it until the job reaches a final status.
\n"}},"type":"object","required":["job_id","experiment_id","status_url"],"title":"EvalExperimentJobAccepted"},"EvalExperimentJobCreateRequestV2":{"properties":{"mode":{"$ref":"#/components/schemas/EvalExperimentJobMode"},"evaluator_ids":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Evaluator Ids"}},"additionalProperties":false,"type":"object","required":["mode"],"title":"EvalExperimentJobCreateRequest"},"EvalExperimentJobErrorResponse":{"properties":{"code":{"type":"string","title":"Code","description":"Stable machine-readable reason: job_launch_failed, job_failed, job_cancelled, job_timed_out, job_terminated or job_history_unavailable.","x-gitbook-description-html":"Stable machine-readable reason: job_launch_failed, job_failed, job_cancelled, job_timed_out, job_terminated or job_history_unavailable.
\n"},"message":{"type":"string","title":"Message","description":"Short human-readable explanation, safe to show to end users.","x-gitbook-description-html":"Short human-readable explanation, safe to show to end users.
\n"}},"type":"object","required":["code","message"],"title":"EvalExperimentJobError"},"EvalExperimentJobMode":{"type":"string","enum":["generate","score"],"title":"EvalExperimentJobMode","description":"What a job does.\n\ngenerate: produce outputs for the experiment's rows, and score them when evaluators were\nselected. score: score existing outputs only; nothing is regenerated.","x-gitbook-description-html":"What a job does.
\ngenerate: produce outputs for the experiment's rows, and score them when evaluators were\nselected. score: score existing outputs only; nothing is regenerated.
\n"},"EvalExperimentJobResponseV2":{"properties":{"job_id":{"type":"string","format":"uuid","title":"Job Id","description":"Unique ID of this job. Each accepted job request creates a new one.","x-gitbook-description-html":"Unique ID of this job. Each accepted job request creates a new one.
\n"},"experiment_id":{"type":"string","format":"uuid","title":"Experiment Id","description":"The experiment this job works on.","x-gitbook-description-html":"The experiment this job works on.
\n"},"mode":{"$ref":"#/components/schemas/EvalExperimentJobMode","description":"What the job does: generate outputs for the experiment's rows, optionally scoring them, or score existing outputs.","x-gitbook-description-html":"What the job does: generate outputs for the experiment's rows, optionally scoring them, or score existing outputs.
\n"},"evaluator_ids":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Evaluator Ids"},"status":{"$ref":"#/components/schemas/EvalExperimentJobStatus","description":"Lifecycle state. queued and running are in progress; completed, completed_with_failures, failed and cancelled are final.","x-gitbook-description-html":"Lifecycle state. queued and running are in progress; completed, completed_with_failures, failed and cancelled are final.
\n"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When the request was accepted.","x-gitbook-description-html":"When the request was accepted.
\n"},"started_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Started At","description":"When a worker started the job. Null while the job is queued.","x-gitbook-description-html":"When a worker started the job. Null while the job is queued.
\n"},"finished_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Finished At","description":"When the job reached a final status. Null while queued or running.","x-gitbook-description-html":"When the job reached a final status. Null while queued or running.
\n"},"last_activity_at":{"type":"string","format":"date-time","title":"Last Activity At","description":"Last time the job's state changed.","x-gitbook-description-html":"Last time the job's state changed.
\n"},"error":{"anyOf":[{"$ref":"#/components/schemas/EvalExperimentJobErrorResponse"},{"type":"null"}],"description":"Why the job ended early. Null unless status is failed or cancelled.","x-gitbook-description-html":"Why the job ended early. Null unless status is failed or cancelled.
\n"}},"type":"object","required":["job_id","experiment_id","mode","evaluator_ids","status","created_at","started_at","finished_at","last_activity_at","error"],"title":"EvalExperimentJob"},"EvalExperimentJobStatus":{"type":"string","enum":["queued","running","completed","completed_with_failures","failed","cancelled"],"title":"EvalExperimentJobStatus","description":"Lifecycle of a job.\n\nqueued and running are in progress. completed, completed_with_failures, failed and cancelled\nare final; completed_with_failures means the job finished but some rows or scores failed.","x-gitbook-description-html":"Lifecycle of a job.
\nqueued and running are in progress. completed, completed_with_failures, failed and cancelled\nare final; completed_with_failures means the job finished but some rows or scores failed.
\n"},"EvalExperimentResponseV2":{"properties":{"experiment_id":{"type":"string","format":"uuid","title":"Experiment Id"},"project_id":{"type":"string","title":"Project Id"},"dataset_id":{"type":"string","format":"uuid","title":"Dataset Id"},"dataset_name":{"type":"string","title":"Dataset Name"},"project_version_id":{"anyOf":[{"type":"string","const":"draft"},{"type":"integer","minimum":0}],"title":"Project Version Id"},"node_contract":{"$ref":"#/components/schemas/EvalNodeContractV2"},"name":{"type":"string","title":"Name"},"notes":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Notes"},"created_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Created By"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["experiment_id","project_id","dataset_id","dataset_name","project_version_id","node_contract","name","notes","created_by","created_at","updated_at"],"title":"EvalExperiment"},"EvalExperimentRowResponseV2":{"properties":{"experiment_row_id":{"type":"string","format":"uuid","title":"Experiment Row Id"},"experiment_id":{"type":"string","format":"uuid","title":"Experiment Id"},"dataset_row_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Dataset Row Id"},"position":{"type":"integer","title":"Position"},"inputs":{"additionalProperties":{"$ref":"#/components/schemas/JsonValue"},"type":"object","title":"Inputs"},"expected_output":{"anyOf":[{"additionalProperties":{"$ref":"#/components/schemas/JsonValue"},"type":"object"},{"type":"null"}],"title":"Expected Output"},"generated_output":{"anyOf":[{"additionalProperties":{"$ref":"#/components/schemas/JsonValue"},"type":"object"},{"type":"null"}],"title":"Generated Output"},"run_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Run Id"},"status":{"$ref":"#/components/schemas/EvalExperimentRowStatus"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error"},"latency_seconds":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Latency Seconds"},"total_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total Tokens"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"},"scores":{"items":{"$ref":"#/components/schemas/EvalScoreResponseV2"},"type":"array","title":"Scores"}},"type":"object","required":["experiment_row_id","experiment_id","dataset_row_id","position","inputs","expected_output","generated_output","run_id","status","error","latency_seconds","total_tokens","created_at","updated_at"],"title":"EvalExperimentRow"},"EvalExperimentRowStatus":{"type":"string","enum":["pending","running","completed","failed"],"title":"EvalExperimentRowStatus","description":"Generation (workflow) lifecycle of an experiment row; judge failures live on scores.","x-gitbook-description-html":"Generation (workflow) lifecycle of an experiment row; judge failures live on scores.
\n"},"EvalExperimentRunStatsResponseV2":{"properties":{"avg_latency_seconds":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Latency Seconds"},"avg_tokens":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Tokens"}},"type":"object","required":["avg_latency_seconds","avg_tokens"],"title":"EvalExperimentRunStats"},"EvalExperimentStatusCountsResponseV2":{"properties":{"pending":{"type":"integer","title":"Pending"},"running":{"type":"integer","title":"Running"},"completed":{"type":"integer","title":"Completed"},"failed":{"type":"integer","title":"Failed"},"total":{"type":"integer","title":"Total"},"done":{"type":"integer","title":"Done"}},"type":"object","required":["pending","running","completed","failed","total","done"],"title":"EvalExperimentStatusCounts"},"EvalExperimentStatusResponseV2":{"properties":{"latest_job":{"anyOf":[{"$ref":"#/components/schemas/EvalExperimentJobResponseV2"},{"type":"null"}]},"job_status_available":{"type":"boolean","title":"Job Status Available"},"status_counts":{"$ref":"#/components/schemas/EvalExperimentStatusCountsResponseV2"},"aggregate_cards":{"items":{"$ref":"#/components/schemas/EvalExperimentAggregateCardResponseV2"},"type":"array","title":"Aggregate Cards"}},"type":"object","required":["latest_job","job_status_available","status_counts","aggregate_cards"],"title":"EvalExperimentStatus"},"EvalExperimentSummaryResponseV2":{"properties":{"experiment":{"$ref":"#/components/schemas/EvalExperimentResponseV2"},"aggregates":{"items":{"$ref":"#/components/schemas/EvalExperimentAggregateResponseV2"},"type":"array","title":"Aggregates"},"run_stats":{"$ref":"#/components/schemas/EvalExperimentRunStatsResponseV2"}},"type":"object","required":["experiment","aggregates","run_stats"],"title":"EvalExperimentSummary"},"EvalExperimentUpdateRequestV2":{"properties":{"name":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"title":"Name"},"notes":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Notes"}},"additionalProperties":false,"type":"object","title":"EvalExperimentUpdateRequest"},"EvalExperimentWarningsResponseV2":{"properties":{"draft_version":{"type":"boolean","title":"Draft Version","default":false},"rows_without_expected_output":{"type":"integer","title":"Rows Without Expected Output","default":0}},"type":"object","title":"EvalExperimentWarnings"},"EvalMonitorAlertResponseV2":{"properties":{"threshold":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Threshold"},"warning_threshold":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Warning Threshold"},"min_samples":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Min Samples"},"window_max_runs":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Window Max Runs"},"window_hours":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Window Hours"},"min_effect_size":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Min Effect Size"},"recovery_threshold":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Recovery Threshold"},"renotify_hours":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Renotify Hours"},"notifications_enabled":{"type":"boolean","title":"Notifications Enabled"},"severity":{"$ref":"#/components/schemas/EvalAlertSeverity"},"effective":{"$ref":"#/components/schemas/EvalAlertEffectiveConfigResponseV2"},"defaults":{"$ref":"#/components/schemas/EvalAlertEffectiveConfigResponseV2"}},"type":"object","required":["threshold","warning_threshold","min_samples","window_max_runs","window_hours","min_effect_size","recovery_threshold","renotify_hours","notifications_enabled","severity","effective","defaults"],"title":"EvalMonitorAlertView"},"EvalMonitorAlertUpdateRequestV2":{"properties":{"threshold":{"anyOf":[{"type":"number","maximum":1,"exclusiveMinimum":0},{"type":"null"}],"title":"Threshold"},"warning_threshold":{"anyOf":[{"type":"number","maximum":1,"exclusiveMinimum":0},{"type":"null"}],"title":"Warning Threshold"},"min_samples":{"anyOf":[{"type":"integer","maximum":2147483647,"minimum":1},{"type":"null"}],"title":"Min Samples"},"window_max_runs":{"anyOf":[{"type":"integer","maximum":2147483647,"minimum":1},{"type":"null"}],"title":"Window Max Runs"},"window_hours":{"anyOf":[{"type":"integer","maximum":8760,"minimum":1},{"type":"null"}],"title":"Window Hours"},"min_effect_size":{"anyOf":[{"type":"number","maximum":1,"minimum":0},{"type":"null"}],"title":"Min Effect Size"},"recovery_threshold":{"anyOf":[{"type":"number","maximum":1,"exclusiveMinimum":0},{"type":"null"}],"title":"Recovery Threshold"},"renotify_hours":{"anyOf":[{"type":"integer","maximum":2147483647,"minimum":1},{"type":"null"}],"title":"Renotify Hours"},"notifications_enabled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Notifications Enabled"}},"additionalProperties":false,"type":"object","title":"EvalMonitorAlertUpdateRequest"},"EvalMonitorCreateRequestV2":{"properties":{"project_id":{"type":"string","minLength":1,"title":"Project Id"},"name":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"title":"Name"},"evaluator_id":{"type":"string","format":"uuid","title":"Evaluator Id"},"notifications_enabled":{"type":"boolean","title":"Notifications Enabled","default":true},"sampling_rate":{"type":"number","maximum":0.3,"exclusiveMinimum":0,"title":"Sampling Rate","default":0.3},"max_runs_daily":{"type":"integer","maximum":1000,"minimum":1,"title":"Max Runs Daily","default":1000}},"additionalProperties":false,"type":"object","required":["project_id","evaluator_id"],"title":"EvalMonitorCreateRequest"},"EvalMonitorEvaluatorRollupResponseV2":{"properties":{"evaluator_id":{"type":"string","format":"uuid","title":"Evaluator Id"},"evaluator_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Evaluator Name"},"score_kind":{"$ref":"#/components/schemas/EvalScoreKind"},"aggregate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Aggregate"}},"type":"object","required":["evaluator_id","evaluator_name","score_kind","aggregate"],"title":"EvalMonitorEvaluatorRollup"},"EvalMonitorEvaluatorTrendResponseV2":{"properties":{"evaluator_id":{"type":"string","format":"uuid","title":"Evaluator Id"},"evaluator_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Evaluator Name"},"score_kind":{"$ref":"#/components/schemas/EvalScoreKind"},"window_aggregate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Window Aggregate"},"scored_count":{"type":"integer","title":"Scored Count"},"failed_count":{"type":"integer","title":"Failed Count"},"buckets":{"items":{"$ref":"#/components/schemas/EvalMonitorTrendBucketResponseV2"},"type":"array","title":"Buckets"},"choice_segments":{"items":{"$ref":"#/components/schemas/EvalChoiceSegmentResponseV2"},"type":"array","title":"Choice Segments"}},"type":"object","required":["evaluator_id","evaluator_name","score_kind","window_aggregate","scored_count","failed_count","buckets","choice_segments"],"title":"EvalMonitorEvaluatorTrend"},"EvalMonitorLimitsResponseV2":{"properties":{"sampling_rate_limit":{"type":"number","title":"Sampling Rate Limit","default":0.3},"max_runs_daily_limit":{"type":"integer","title":"Max Runs Daily Limit","default":1000},"sampling_rate_default":{"type":"number","title":"Sampling Rate Default","default":0.3},"max_runs_daily_default":{"type":"integer","title":"Max Runs Daily Default","default":1000}},"type":"object","title":"EvalMonitorLimits"},"EvalMonitorListItemResponseV2":{"properties":{"monitor":{"$ref":"#/components/schemas/EvalMonitorResponseV2"},"severity":{"$ref":"#/components/schemas/EvalAlertSeverity"},"runs_scored_in_window":{"type":"integer","title":"Runs Scored In Window"},"runs_enqueued_today":{"type":"integer","title":"Runs Enqueued Today"},"evaluators":{"items":{"$ref":"#/components/schemas/EvalMonitorEvaluatorRollupResponseV2"},"type":"array","title":"Evaluators"}},"type":"object","required":["monitor","severity","runs_scored_in_window","runs_enqueued_today","evaluators"],"title":"EvalMonitorListItem"},"EvalMonitorResponseV2":{"properties":{"monitor_id":{"type":"string","format":"uuid","title":"Monitor Id"},"project_id":{"type":"string","title":"Project Id"},"evaluator_id":{"type":"string","format":"uuid","title":"Evaluator Id"},"name":{"type":"string","title":"Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"enabled":{"type":"boolean","title":"Enabled"},"sampling_rate":{"type":"number","title":"Sampling Rate"},"max_runs_daily":{"type":"integer","title":"Max Runs Daily"},"created_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Created By"},"updated_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Updated By"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["monitor_id","project_id","evaluator_id","name","description","enabled","sampling_rate","max_runs_daily","created_by","updated_by","created_at","updated_at"],"title":"EvalMonitor"},"EvalMonitorSampledRunResponseV2":{"properties":{"run_id":{"type":"string","format":"uuid","title":"Run Id"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"input_snapshot":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Input Snapshot"},"output_snapshot":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Output Snapshot"},"scores":{"items":{"$ref":"#/components/schemas/EvalScoreResponseV2"},"type":"array","title":"Scores"}},"type":"object","required":["run_id","created_at","input_snapshot","output_snapshot","scores"],"title":"EvalMonitorSampledRun"},"EvalMonitorScoreStatsResponseV2":{"properties":{"pending_count":{"type":"integer","title":"Pending Count"},"scored_count":{"type":"integer","title":"Scored Count"},"failed_count":{"type":"integer","title":"Failed Count"},"runs_enqueued_today":{"type":"integer","title":"Runs Enqueued Today"},"evaluators":{"items":{"$ref":"#/components/schemas/EvalMonitorEvaluatorTrendResponseV2"},"type":"array","title":"Evaluators"}},"type":"object","required":["pending_count","scored_count","failed_count","runs_enqueued_today","evaluators"],"title":"EvalMonitorScoreStats"},"EvalMonitorTrendBucketResponseV2":{"properties":{"bucket_start":{"type":"string","format":"date-time","title":"Bucket Start"},"aggregate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Aggregate"},"scored_count":{"type":"integer","title":"Scored Count"},"failed_count":{"type":"integer","title":"Failed Count"}},"type":"object","required":["bucket_start","aggregate","scored_count","failed_count"],"title":"EvalMonitorTrendBucket"},"EvalMonitorUpdateRequestV2":{"properties":{"name":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"title":"Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"enabled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Enabled"},"sampling_rate":{"anyOf":[{"type":"number","maximum":0.3,"exclusiveMinimum":0},{"type":"null"}],"title":"Sampling Rate"},"max_runs_daily":{"anyOf":[{"type":"integer","maximum":1000,"minimum":1},{"type":"null"}],"title":"Max Runs Daily"}},"additionalProperties":false,"type":"object","title":"EvalMonitorUpdateRequest"},"EvalNodeContractRequestV2":{"properties":{"input_kind":{"type":"string","enum":["start_node","legacy_input_nodes"],"title":"Input Kind"},"input_keys":{"items":{"type":"string"},"type":"array","maxItems":1,"minItems":1,"title":"Input Keys"},"output_node_ids":{"items":{"type":"string"},"type":"array","maxItems":1,"minItems":1,"title":"Output Node Ids"}},"additionalProperties":false,"type":"object","required":["input_kind","input_keys","output_node_ids"],"title":"EvalNodeContractRequest"},"EvalNodeContractV2":{"properties":{"input_kind":{"type":"string","enum":["start_node","legacy_input_nodes"],"title":"Input Kind"},"input_keys":{"items":{"type":"string"},"type":"array","title":"Input Keys"},"output_node_ids":{"items":{"type":"string"},"type":"array","title":"Output Node Ids"}},"type":"object","required":["input_kind","input_keys","output_node_ids"],"title":"EvalNodeContract"},"EvalPreviewSampleRequestV2":{"properties":{"inputs":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Inputs"},"generated_output":{"additionalProperties":true,"type":"object","title":"Generated Output"},"expected_output":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Expected Output"}},"additionalProperties":false,"type":"object","required":["generated_output"],"title":"EvalPreviewSampleRequest"},"EvalRunScoreCreateRequestV2":{"properties":{"evaluator_id":{"type":"string","format":"uuid","title":"Evaluator Id"}},"additionalProperties":false,"type":"object","required":["evaluator_id"],"title":"EvalRunScoreCreateRequest"},"EvalRunScoreResponseV2":{"properties":{"score_id":{"type":"string","format":"uuid","title":"Score Id"},"project_id":{"type":"string","title":"Project Id"},"experiment_row_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Experiment Row Id"},"run_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Run Id"},"project_version_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Project Version Id"},"evaluator_id":{"type":"string","format":"uuid","title":"Evaluator Id"},"score_kind":{"$ref":"#/components/schemas/EvalScoreKind"},"score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Score"},"choice_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Choice Label"},"feedback":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Feedback"},"status":{"$ref":"#/components/schemas/EvalScoreStatus"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error"},"input_snapshot":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Input Snapshot"},"output_snapshot":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Output Snapshot"},"created_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Created By"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"},"evaluator_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Evaluator Name"}},"type":"object","required":["score_id","project_id","experiment_row_id","run_id","project_version_id","evaluator_id","score_kind","score","choice_label","feedback","status","error","input_snapshot","output_snapshot","created_by","created_at","updated_at","evaluator_name"],"title":"EvalRunScore"},"EvalScoreKind":{"type":"string","enum":["numeric","boolean"],"title":"EvalScoreKind","description":"Drives aggregate rendering: mean for numeric, pass-rate for boolean.","x-gitbook-description-html":"Drives aggregate rendering: mean for numeric, pass-rate for boolean.
\n"},"EvalScoreResponseV2":{"properties":{"score_id":{"type":"string","format":"uuid","title":"Score Id"},"project_id":{"type":"string","title":"Project Id"},"experiment_row_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Experiment Row Id"},"run_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Run Id"},"project_version_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Project Version Id"},"evaluator_id":{"type":"string","format":"uuid","title":"Evaluator Id"},"score_kind":{"$ref":"#/components/schemas/EvalScoreKind"},"score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Score"},"choice_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Choice Label"},"feedback":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Feedback"},"status":{"$ref":"#/components/schemas/EvalScoreStatus"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error"},"input_snapshot":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Input Snapshot"},"output_snapshot":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Output Snapshot"},"created_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Created By"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["score_id","project_id","experiment_row_id","run_id","project_version_id","evaluator_id","score_kind","score","choice_label","feedback","status","error","input_snapshot","output_snapshot","created_by","created_at","updated_at"],"title":"EvalScore"},"EvalScoreStatus":{"type":"string","enum":["pending","scoring","scored","failed"],"title":"EvalScoreStatus","description":"Judge/rule outcome for a score row; pending/scoring are the monitor queue states.","x-gitbook-description-html":"Judge/rule outcome for a score row; pending/scoring are the monitor queue states.
\n"},"EvaluatorCreateRequestV2":{"properties":{"project_id":{"type":"string","minLength":1,"title":"Project Id"},"name":{"type":"string","maxLength":200,"minLength":1,"title":"Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"evaluator_type":{"$ref":"#/components/schemas/EvaluatorType"},"config":{"additionalProperties":true,"type":"object","title":"Config"},"judge_provider":{"anyOf":[{"$ref":"#/components/schemas/LLMProviderEnum"},{"type":"null"}]},"judge_model_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Judge Model Id"},"node_contract":{"$ref":"#/components/schemas/EvalNodeContractRequestV2"}},"additionalProperties":false,"type":"object","required":["project_id","name","evaluator_type","config","node_contract"],"title":"EvaluatorCreateRequest"},"EvaluatorPreviewRequestV2":{"properties":{"project_id":{"type":"string","minLength":1,"title":"Project Id"},"evaluator_type":{"$ref":"#/components/schemas/EvaluatorType"},"config":{"additionalProperties":true,"type":"object","title":"Config"},"judge_provider":{"anyOf":[{"$ref":"#/components/schemas/LLMProviderEnum"},{"type":"null"}]},"judge_model_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Judge Model Id"},"samples":{"items":{"$ref":"#/components/schemas/EvalPreviewSampleRequestV2"},"type":"array","maxItems":3,"minItems":1,"title":"Samples"}},"additionalProperties":false,"type":"object","required":["project_id","evaluator_type","config","samples"],"title":"EvaluatorPreviewRequest"},"EvaluatorPreviewResponseV2":{"properties":{"score_kind":{"$ref":"#/components/schemas/EvalScoreKind"},"score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Score"},"choice_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Choice Label"},"feedback":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Feedback"},"status":{"$ref":"#/components/schemas/EvalScoreStatus"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error"}},"type":"object","required":["score_kind","score","choice_label","feedback","status","error"],"title":"EvaluatorPreview"},"EvaluatorResponseV2":{"properties":{"evaluator_id":{"type":"string","format":"uuid","title":"Evaluator Id"},"project_id":{"type":"string","title":"Project Id"},"name":{"type":"string","title":"Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"evaluator_type":{"$ref":"#/components/schemas/EvaluatorType"},"version_number":{"type":"integer","title":"Version Number"},"node_contract":{"$ref":"#/components/schemas/EvalNodeContractV2"},"config":{"additionalProperties":true,"type":"object","title":"Config"},"score_kind":{"$ref":"#/components/schemas/EvalScoreKind"},"uses_input":{"type":"boolean","title":"Uses Input"},"uses_expected_output":{"type":"boolean","title":"Uses Expected Output"},"judge_provider":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Judge Provider"},"judge_model_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Judge Model Id"},"created_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Created By"},"updated_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Updated By"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["evaluator_id","project_id","name","description","evaluator_type","version_number","node_contract","config","score_kind","uses_input","uses_expected_output","judge_provider","judge_model_id","created_by","updated_by","created_at","updated_at"],"title":"Evaluator"},"EvaluatorTemplateResponseV2":{"properties":{"template_id":{"type":"string","title":"Template Id"},"name":{"type":"string","title":"Name"},"evaluator_type":{"$ref":"#/components/schemas/EvaluatorType"},"config":{"additionalProperties":true,"type":"object","title":"Config"}},"type":"object","required":["template_id","name","evaluator_type","config"],"title":"EvaluatorTemplate"},"EvaluatorType":{"type":"string","enum":["llm_judge","builtin_rule"],"title":"EvaluatorType","description":"How an evaluator scores: LLM judge or built-in rule.","x-gitbook-description-html":"How an evaluator scores: LLM judge or built-in rule.
\n"},"EvaluatorUpdateRequestV2":{"properties":{"name":{"anyOf":[{"type":"string","maxLength":200,"minLength":1},{"type":"null"}],"title":"Name","description":"New name. Omit or send null to keep the current name.","x-gitbook-description-html":"New name. Omit or send null to keep the current name.
\n"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"New description. Omit to keep the current description; send null to clear it. Example: `{\"description\": null}`."},"config":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Config","description":"Replaces the entire evaluator configuration. Omit or send null to keep the current configuration.","x-gitbook-description-html":"Replaces the entire evaluator configuration. Omit or send null to keep the current configuration.
\n"},"judge_provider":{"anyOf":[{"$ref":"#/components/schemas/LLMProviderEnum"},{"type":"null"}],"description":"LLM judge provider override. Omit to keep it; send null to clear it. Any existing judge_model_id override must also be cleared when removing the provider. Example: `{\"judge_provider\": null, \"judge_model_id\": null}`.","x-gitbook-description-html":"LLM judge provider override. Omit to keep it; send null to clear it. Any existing judge_model_id override must also be cleared when removing the provider. Example: {"judge_provider": null, "judge_model_id": null}.
LLM judge model override. Omit to keep it; send null to clear it. A model override requires a provider override in the resulting configuration. Example: {"judge_model_id": null}.
Replacement evaluator contract. Omit or send null to keep the current contract. A changed contract creates a new evaluator version.
\n"}},"additionalProperties":false,"type":"object","title":"EvaluatorUpdateRequest","examples":[{"description":"Updated grading rules"},{"config":{"pattern":"^approved$","rule":"regex"}}]},"ExecutionMode":{"type":"string","enum":["in-memory","remote"],"title":"ExecutionMode","description":"Workflow execution modes.\n\nThese are implementation-agnostic names exposed to clients.","x-gitbook-description-html":"Workflow execution modes.
\nThese are implementation-agnostic names exposed to clients.
\n"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"HitlResponseType":{"type":"string","enum":["text","approval","choice"],"title":"HitlResponseType","description":"Response types accepted by the public ask_human resume API.\n\nMirrors the ask_human action's own ``Literal[\"text\", \"approval\", \"choice\"]`` (defined in\nstackflow); kept as a separate enum because apps cannot reuse that stackflow Literal.","x-gitbook-description-html":"Response types accepted by the public ask_human resume API.
\nMirrors the ask_human action's own Literal["text", "approval", "choice"] (defined in\nstackflow); kept as a separate enum because apps cannot reuse that stackflow Literal.
Chunking strategy for splitting documents during indexing.
\n"},"KnowledgeBaseFileResponse":{"properties":{"knowledge_base_id":{"type":"string","format":"uuid","title":"Knowledge Base Id"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"modified_at":{"type":"string","format":"date-time","title":"Modified At"},"indexed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Indexed At"},"resource_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Resource Id"},"resource_path":{"type":"string","minLength":1,"title":"Resource Path"},"dataloader_metadata":{"patternProperties":{"^[^\\t\\n\\r\\f\\v]+$":{"anyOf":[{},{"type":"null"}]}},"propertyNames":{"maxLength":64,"minLength":1},"type":"object","title":"Dataloader Metadata"},"user_metadata":{"patternProperties":{"^[^\\t\\n\\r\\f\\v]+$":{"anyOf":[{},{"type":"null"}]}},"propertyNames":{"maxLength":64,"minLength":1},"type":"object","title":"User Metadata"},"content_hash":{"type":"string","minLength":1,"title":"Content Hash"},"content_mime":{"type":"string","minLength":1,"title":"Content Mime"},"size":{"type":"integer","minimum":0,"title":"Size"},"status":{"$ref":"#/components/schemas/StackFileStatusEnum"},"effective_permissions":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Effective Permissions","description":"Viewer's effective permissions for this file; null when not computed.","x-gitbook-description-html":"Viewer's effective permissions for this file; null when not computed.
\n"}},"type":"object","required":["knowledge_base_id","created_at","modified_at","resource_id","resource_path","content_hash","content_mime","size","status"],"title":"KnowledgeBaseFileResponse","description":"A file stored in a knowledge base.","x-gitbook-description-html":"A file stored in a knowledge base.
\n"},"KnowledgeBaseFileResponseV2":{"properties":{"knowledge_base_id":{"type":"string","format":"uuid","title":"Knowledge Base Id"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"modified_at":{"type":"string","format":"date-time","title":"Modified At"},"indexed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Indexed At"},"resource_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Resource Id"},"resource_path":{"type":"string","minLength":1,"title":"Resource Path"},"acl_target_path":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Acl Target Path"},"dataloader_metadata":{"patternProperties":{"^[^\\t\\n\\r\\f\\v]+$":{"anyOf":[{},{"type":"null"}]}},"propertyNames":{"maxLength":64,"minLength":1},"type":"object","title":"Dataloader Metadata"},"user_metadata":{"patternProperties":{"^[^\\t\\n\\r\\f\\v]+$":{"anyOf":[{},{"type":"null"}]}},"propertyNames":{"maxLength":64,"minLength":1},"type":"object","title":"User Metadata"},"content_hash":{"type":"string","minLength":1,"title":"Content Hash"},"content_mime":{"type":"string","minLength":1,"title":"Content Mime"},"size":{"type":"integer","minimum":0,"title":"Size"},"status":{"$ref":"#/components/schemas/StackFileStatusEnum"},"effective_permissions":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Effective Permissions"}},"type":"object","required":["knowledge_base_id","created_at","modified_at","resource_id","resource_path","content_hash","content_mime","size","status"],"title":"KnowledgeBaseFileResponse","description":"A file stored in a knowledge base.","x-gitbook-description-html":"A file stored in a knowledge base.
\n"},"KnowledgeBaseIndexingParamsRequest":{"properties":{"ocr":{"type":"boolean","title":"Ocr","default":false},"embedding_params":{"$ref":"#/components/schemas/CreateKnowledgeBaseEmbeddingParams"},"chunker_params":{"$ref":"#/components/schemas/KnowledgeBaseChunkerParams"}},"type":"object","title":"KnowledgeBaseIndexingParamsRequest","description":"Parameters that control how documents are indexed into a knowledge base.","x-gitbook-description-html":"Parameters that control how documents are indexed into a knowledge base.
\n"},"KnowledgeBaseMetadataSchemasResponseV2":{"properties":{"user":{"anyOf":[{"$ref":"#/components/schemas/MetadataSchemaResponseV2"},{"type":"null"}]},"dataloader":{"anyOf":[{"$ref":"#/components/schemas/MetadataSchemaResponseV2"},{"type":"null"}]}},"type":"object","required":["user","dataloader"],"title":"KnowledgeBaseMetadataSchemas","description":"The user and dataloader metadata schemas for a knowledge base on the public v2 surface.","x-gitbook-description-html":"The user and dataloader metadata schemas for a knowledge base on the public v2 surface.
\n"},"KnowledgeBaseQueryRequestV2":{"properties":{"query":{"type":"string","minLength":1,"title":"Query","description":"The search query to run against the knowledge base.","x-gitbook-description-html":"The search query to run against the knowledge base.
\n"},"top_k":{"type":"integer","maximum":20,"minimum":1,"title":"Top K","description":"Number of top results to return.","default":10,"x-gitbook-description-html":"Number of top results to return.
\n"},"strategy":{"$ref":"#/components/schemas/KnowledgeBaseQueryStrategyV2","description":"Retrieval strategy to use for the search.","default":"semantic","x-gitbook-description-html":"Retrieval strategy to use for the search.
\n"},"retrieval_type":{"$ref":"#/components/schemas/RetrievalType","description":"Type of retrieval to use for the search.","default":"chunks","x-gitbook-description-html":"Type of retrieval to use for the search.
\n"}},"additionalProperties":false,"type":"object","required":["query"],"title":"KnowledgeBaseQueryRequest","description":"A query against a knowledge base on the public v2 surface.","x-gitbook-description-html":"A query against a knowledge base on the public v2 surface.
\n"},"KnowledgeBaseQueryResultV2":{"properties":{"content":{"type":"string","title":"Content"},"score":{"type":"number","title":"Score","default":0},"resource_id":{"type":"string","format":"uuid","title":"Resource Id"}},"type":"object","required":["content","resource_id"],"title":"KnowledgeBaseQueryResult","description":"A single retrieved result on the public v2 surface.","x-gitbook-description-html":"A single retrieved result on the public v2 surface.
\n"},"KnowledgeBaseQueryStrategyV2":{"type":"string","enum":["semantic","keyword","hybrid"],"title":"KnowledgeBaseQueryStrategyV2","description":"Retrieval strategy for a public v2 knowledge base query.","x-gitbook-description-html":"Retrieval strategy for a public v2 knowledge base query.
\n"},"KnowledgeBaseResourcesResponse":{"additionalProperties":true,"type":"object"},"KnowledgeBaseResponse":{"properties":{"knowledge_base_id":{"type":"string","format":"uuid","title":"Knowledge Base Id"},"connection_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Connection Id"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"},"connection_source_ids":{"items":{"type":"string"},"type":"array","uniqueItems":true,"title":"Connection Source Ids"},"website_sources":{"items":{"$ref":"#/components/schemas/SelectedWebsiteSource"},"type":"array","title":"Website Sources"},"source_file_authorization_enabled":{"type":"boolean","title":"Source File Authorization Enabled"},"connection_provider_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Connection Provider Type"},"is_empty":{"type":"boolean","title":"Is Empty","default":true},"total_size":{"type":"integer","title":"Total Size","description":"Total size of all files in the knowledge base, in bytes.","default":0,"x-gitbook-description-html":"Total size of all files in the knowledge base, in bytes.
\n"},"total_files":{"type":"integer","title":"Total Files","description":"Total number of files in the knowledge base.","default":0,"x-gitbook-description-html":"Total number of files in the knowledge base.
\n"},"total_indexed_files":{"type":"integer","title":"Total Indexed Files","description":"Total number of successfully indexed files.","default":0,"x-gitbook-description-html":"Total number of successfully indexed files.
\n"},"total_error_files":{"type":"integer","title":"Total Error Files","description":"Total number of files that failed indexing.","default":0,"x-gitbook-description-html":"Total number of files that failed indexing.
\n"},"last_synced_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Synced At","description":"Timestamp when the knowledge base was last successfully synced from its source","x-gitbook-description-html":"Timestamp when the knowledge base was last successfully synced from its source
\n"},"name":{"type":"string","maxLength":2048,"minLength":1,"title":"Name","default":"Unnamed Knowledge Base"},"description":{"type":"string","maxLength":2048,"title":"Description","default":""},"indexing_params":{"$ref":"#/components/schemas/KnowledgeBaseResponseIndexingParams"},"org_id":{"type":"string","title":"Org Id"},"role":{"anyOf":[{"$ref":"#/components/schemas/KnowledgeBaseRole"},{"type":"null"}]},"org_level_role":{"anyOf":[{"$ref":"#/components/schemas/KnowledgeBaseRole"},{"type":"null"}]},"user_metadata_schema":{"anyOf":[{"$ref":"#/components/schemas/MetadataSchema"},{"type":"null"}]},"dataloader_metadata_schema":{"anyOf":[{"$ref":"#/components/schemas/MetadataSchema"},{"type":"null"}]}},"type":"object","required":["knowledge_base_id","connection_id","created_at","updated_at","connection_source_ids","website_sources","source_file_authorization_enabled","indexing_params","org_id"],"title":"KnowledgeBaseResponse","description":"A knowledge base.","x-gitbook-description-html":"A knowledge base.
\n"},"KnowledgeBaseResponseEmbeddingParams":{"properties":{"embedding_model":{"type":"string","title":"Embedding Model"},"api_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}},"type":"object","required":["embedding_model"],"title":"KnowledgeBaseResponseEmbeddingParams","description":"Embedding configuration of a knowledge base.","x-gitbook-description-html":"Embedding configuration of a knowledge base.
\n"},"KnowledgeBaseResponseIndexingParams":{"properties":{"ocr":{"type":"boolean","title":"Ocr","default":false},"embedding_params":{"$ref":"#/components/schemas/KnowledgeBaseResponseEmbeddingParams"},"chunker_params":{"$ref":"#/components/schemas/KnowledgeBaseChunkerParams"}},"type":"object","required":["embedding_params"],"title":"KnowledgeBaseResponseIndexingParams","description":"Indexing configuration of a knowledge base.","x-gitbook-description-html":"Indexing configuration of a knowledge base.
\n"},"KnowledgeBaseResponseV2":{"properties":{"knowledge_base_id":{"type":"string","format":"uuid","title":"Knowledge Base Id"},"connection_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Connection Id"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"},"connection_source_ids":{"items":{"type":"string"},"type":"array","uniqueItems":true,"title":"Connection Source Ids"},"website_sources":{"items":{"$ref":"#/components/schemas/SelectedWebsiteSource"},"type":"array","title":"Website Sources"},"source_file_authorization_enabled":{"type":"boolean","title":"Source File Authorization Enabled"},"connection_provider_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Connection Provider Type"},"is_empty":{"type":"boolean","title":"Is Empty","default":true},"total_size":{"type":"integer","title":"Total Size","default":0},"total_files":{"type":"integer","title":"Total Files","default":0},"total_indexed_files":{"type":"integer","title":"Total Indexed Files","default":0},"total_error_files":{"type":"integer","title":"Total Error Files","default":0},"last_synced_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Synced At"},"name":{"type":"string","maxLength":2048,"minLength":1,"title":"Name","default":"Unnamed Knowledge Base"},"description":{"type":"string","maxLength":2048,"title":"Description","default":""},"indexing_params":{"$ref":"#/components/schemas/KnowledgeBaseResponseIndexingParams"},"org_level_role":{"anyOf":[{"$ref":"#/components/schemas/KnowledgeBaseRole"},{"type":"null"}]},"role":{"anyOf":[{"$ref":"#/components/schemas/KnowledgeBaseRole"},{"type":"null"}]}},"type":"object","required":["knowledge_base_id","connection_id","created_at","updated_at","connection_source_ids","website_sources","source_file_authorization_enabled","indexing_params"],"title":"KnowledgeBaseResponse","description":"A knowledge base on the public v2 surface.","x-gitbook-description-html":"A knowledge base on the public v2 surface.
\n"},"KnowledgeBaseRole":{"type":"string","enum":["viewer","editor","admin"],"title":"KnowledgeBaseRole","description":"A user's role within a knowledge base.\n\nOrdered by privilege for Python comparisons. All four ordering operators are\ndefined explicitly because StrEnum subclasses str: its inherited lexicographic\ncomparisons would otherwise apply, so e.g. ``max()`` would pick ``\"viewer\"``\nover ``\"admin\"``. The operators only order Python objects; Postgres enum\nordering is governed by the declaration order above.","x-gitbook-description-html":"A user's role within a knowledge base.
\nOrdered by privilege for Python comparisons. All four ordering operators are\ndefined explicitly because StrEnum subclasses str: its inherited lexicographic\ncomparisons would otherwise apply, so e.g. max() would pick "viewer"\nover "admin". The operators only order Python objects; Postgres enum\nordering is governed by the declaration order above.
Human-readable description of the started task.
\n"},"status":{"type":"string","const":"accepted","title":"Status","description":"Task status.","default":"accepted","x-gitbook-description-html":"Task status.
\n"}},"type":"object","required":["message"],"title":"KnowledgeBaseSyncResponse","description":"Result of a knowledge base sync or reindex request.","x-gitbook-description-html":"Result of a knowledge base sync or reindex request.
\n"},"KnowledgeBaseSyncResponseV2":{"properties":{"message":{"type":"string","title":"Message"},"status":{"type":"string","const":"accepted","title":"Status","default":"accepted"}},"type":"object","required":["message"],"title":"KnowledgeBaseSyncResponse","description":"Acknowledgement that a sync or reindex task was accepted.","x-gitbook-description-html":"Acknowledgement that a sync or reindex task was accepted.
\n"},"LLMConnectionOrigin":{"type":"string","enum":["stack_ai","external_db","external_ephemeral"],"title":"LLMConnectionOrigin"},"LLMProviderEnum":{"type":"string","enum":["Anthropic","Azure","Baseten","Bedrock","Cerebras","Core42","FireworksAI","Google","Google_service_account","Groq","Local","Meta","Mistral","Modular","OpenAI","OpenRouter","Perplexity","Replicate","TogetherAI","XAI"],"title":"LLMProviderEnum","description":"LLM provider identifiers.","x-gitbook-description-html":"LLM provider identifiers.
\n"},"LLMUsageData":{"properties":{"cache_metrics":{"anyOf":[{"$ref":"#/components/schemas/CacheMetrics"},{"type":"null"}]},"provider":{"$ref":"#/components/schemas/LLMProviderEnum"},"model_id":{"type":"string","title":"Model Id"},"tokens":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"title":"Tokens"},"input_tokens":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"title":"Input Tokens","description":"Total prompt tokens processed, INCLUDING any prompt-cache writes and reads (Anthropic reports those outside its raw input counter; they are folded back in before this record is built).","x-gitbook-description-html":"Total prompt tokens processed, INCLUDING any prompt-cache writes and reads (Anthropic reports those outside its raw input counter; they are folded back in before this record is built).
\n"},"output_tokens":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"title":"Output Tokens"},"cache_creation_input_tokens":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"title":"Cache Creation Input Tokens","description":"Subset of input_tokens written to the provider prompt cache this call. Kept separate so billing can later discount cache traffic (writes bill at a premium, reads at a fraction). None when the provider reported no cache counters.","x-gitbook-description-html":"Subset of input_tokens written to the provider prompt cache this call. Kept separate so billing can later discount cache traffic (writes bill at a premium, reads at a fraction). None when the provider reported no cache counters.
\n"},"cache_read_input_tokens":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"title":"Cache Read Input Tokens","description":"Subset of input_tokens served from the provider prompt cache this call. None when the provider reported no cache counters.","x-gitbook-description-html":"Subset of input_tokens served from the provider prompt cache this call. None when the provider reported no cache counters.
\n"},"cache_measurement":{"anyOf":[{"$ref":"#/components/schemas/CacheMeasurement"},{"type":"null"}]},"connection_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Connection Id"},"connection_origin":{"anyOf":[{"$ref":"#/components/schemas/LLMConnectionOrigin"},{"type":"null"}]},"is_local_model":{"type":"boolean","title":"Is Local Model","description":"Whether this usage record is from a local model.","readOnly":true,"x-gitbook-description-html":"Whether this usage record is from a local model.
\n"},"should_charge":{"type":"boolean","title":"Should Charge","description":"Whether this usage record should be charged.","readOnly":true,"x-gitbook-description-html":"Whether this usage record should be charged.
\n"}},"type":"object","required":["provider","model_id","is_local_model","should_charge"],"title":"LLMUsageData","description":"Token usage for a single LLM call within a run.","x-gitbook-description-html":"Token usage for a single LLM call within a run.
\n"},"MetadataPropertyBaseResponseV2":{"properties":{"type":{"type":"string","enum":["number","boolean","date"],"title":"Type"},"description":{"type":"string","title":"Description"},"order":{"type":"integer","title":"Order"}},"type":"object","required":["type","description","order"],"title":"MetadataPropertyResponse","description":"Shared fields for every metadata property on the public v2 surface.\n\nUsed directly for property types that add no extra fields (number, boolean,\ndate); string and string-list subclass it below for their extra fields.","x-gitbook-description-html":"Shared fields for every metadata property on the public v2 surface.
\nUsed directly for property types that add no extra fields (number, boolean,\ndate); string and string-list subclass it below for their extra fields.
\n"},"MetadataSchema":{"properties":{"properties":{"patternProperties":{"^[^\\t\\n\\r\\f\\v]+$":{"anyOf":[{"$ref":"#/components/schemas/StringProperty"},{"$ref":"#/components/schemas/NumberProperty"},{"$ref":"#/components/schemas/BooleanProperty"},{"$ref":"#/components/schemas/DateProperty"},{"$ref":"#/components/schemas/StringListProperty"}]}},"propertyNames":{"maxLength":64,"minLength":1},"type":"object","title":"Properties"}},"type":"object","required":["properties"],"title":"MetadataSchema"},"MetadataSchemaResponseV2":{"properties":{"properties":{"patternProperties":{"^[^\\t\\n\\r\\f\\v]+$":{"oneOf":[{"$ref":"#/components/schemas/MetadataStringPropertyResponseV2"},{"$ref":"#/components/schemas/MetadataPropertyBaseResponseV2"},{"$ref":"#/components/schemas/MetadataStringListPropertyResponseV2"}],"discriminator":{"propertyName":"type","mapping":{"boolean":"#/components/schemas/MetadataPropertyBaseResponseV2","date":"#/components/schemas/MetadataPropertyBaseResponseV2","number":"#/components/schemas/MetadataPropertyBaseResponseV2","string":"#/components/schemas/MetadataStringPropertyResponseV2","string_list":"#/components/schemas/MetadataStringListPropertyResponseV2"}}}},"propertyNames":{"maxLength":64,"minLength":1},"type":"object","title":"Properties"}},"type":"object","required":["properties"],"title":"MetadataSchema","description":"A metadata schema (user or dataloader) on the public v2 surface.","x-gitbook-description-html":"A metadata schema (user or dataloader) on the public v2 surface.
\n"},"MetadataStringListOptionResponseV2":{"properties":{"id":{"type":"string","title":"Id"},"label":{"type":"string","title":"Label"},"description":{"type":"string","title":"Description"},"color":{"$ref":"#/components/schemas/StringListOptionColor"},"order":{"type":"integer","title":"Order"}},"type":"object","required":["id","label","description","color","order"],"title":"MetadataStringListOptionResponse","description":"A selectable option for a string-list metadata property.","x-gitbook-description-html":"A selectable option for a string-list metadata property.
\n"},"MetadataStringListPropertyResponseV2":{"properties":{"type":{"type":"string","const":"string_list","title":"Type","default":"string_list"},"description":{"type":"string","title":"Description"},"order":{"type":"integer","title":"Order"},"options":{"items":{"$ref":"#/components/schemas/MetadataStringListOptionResponseV2"},"type":"array","title":"Options"}},"type":"object","required":["description","order","options"],"title":"MetadataStringListPropertyResponse","description":"A string-list-valued metadata property on the public v2 surface.","x-gitbook-description-html":"A string-list-valued metadata property on the public v2 surface.
\n"},"MetadataStringPropertyResponseV2":{"properties":{"type":{"type":"string","const":"string","title":"Type","default":"string"},"description":{"type":"string","title":"Description"},"order":{"type":"integer","title":"Order"},"subtype":{"$ref":"#/components/schemas/StringSubtypeEnum"}},"type":"object","required":["description","order","subtype"],"title":"MetadataStringPropertyResponse","description":"A string-valued metadata property on the public v2 surface.","x-gitbook-description-html":"A string-valued metadata property on the public v2 surface.
\n"},"NumberProperty":{"properties":{"type":{"type":"string","const":"number","title":"Type","default":"number"},"description":{"type":"string","maxLength":1024,"title":"Description","default":""},"order":{"type":"integer","minimum":0,"title":"Order","description":"Display order of this property within the schema.","default":0,"x-gitbook-description-html":"Display order of this property within the schema.
\n"}},"type":"object","title":"NumberProperty"},"OffsetBasedPaginationResponse_ConnectionResponseV2_":{"properties":{"response_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Response Code","description":"Machine-readable response code, when provided.","x-gitbook-description-html":"Machine-readable response code, when provided.
\n"},"meta":{"additionalProperties":true,"type":"object","title":"Meta","description":"Additional metadata","default":{},"x-gitbook-description-html":"Additional metadata
\n"},"data":{"items":{"$ref":"#/components/schemas/ConnectionResponseV2"},"type":"array","title":"Data"},"offset":{"type":"integer","minimum":0,"title":"Offset","default":0},"limit":{"type":"integer","minimum":0,"title":"Limit","default":50},"total":{"type":"integer","minimum":0,"title":"Total","default":0}},"type":"object","title":"OffsetBasedPaginationResponse[ConnectionResponseV2]"},"OffsetBasedPaginationResponse_EvalDatasetListItemResponseV2_":{"properties":{"response_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Response Code","description":"Machine-readable response code, when provided.","x-gitbook-description-html":"Machine-readable response code, when provided.
\n"},"meta":{"additionalProperties":true,"type":"object","title":"Meta","description":"Additional metadata","default":{},"x-gitbook-description-html":"Additional metadata
\n"},"data":{"items":{"$ref":"#/components/schemas/EvalDatasetListItemResponseV2"},"type":"array","title":"Data"},"offset":{"type":"integer","minimum":0,"title":"Offset","default":0},"limit":{"type":"integer","minimum":0,"title":"Limit","default":50},"total":{"type":"integer","minimum":0,"title":"Total","default":0}},"type":"object","title":"OffsetBasedPaginationResponse[EvalDatasetListItemResponseV2]"},"OffsetBasedPaginationResponse_EvalDatasetRowResponseV2_":{"properties":{"response_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Response Code","description":"Machine-readable response code, when provided.","x-gitbook-description-html":"Machine-readable response code, when provided.
\n"},"meta":{"additionalProperties":true,"type":"object","title":"Meta","description":"Additional metadata","default":{},"x-gitbook-description-html":"Additional metadata
\n"},"data":{"items":{"$ref":"#/components/schemas/EvalDatasetRowResponseV2"},"type":"array","title":"Data"},"offset":{"type":"integer","minimum":0,"title":"Offset","default":0},"limit":{"type":"integer","minimum":0,"title":"Limit","default":50},"total":{"type":"integer","minimum":0,"title":"Total","default":0}},"type":"object","title":"OffsetBasedPaginationResponse[EvalDatasetRowResponseV2]"},"OffsetBasedPaginationResponse_EvalExperimentRowResponseV2_":{"properties":{"response_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Response Code","description":"Machine-readable response code, when provided.","x-gitbook-description-html":"Machine-readable response code, when provided.
\n"},"meta":{"additionalProperties":true,"type":"object","title":"Meta","description":"Additional metadata","default":{},"x-gitbook-description-html":"Additional metadata
\n"},"data":{"items":{"$ref":"#/components/schemas/EvalExperimentRowResponseV2"},"type":"array","title":"Data"},"offset":{"type":"integer","minimum":0,"title":"Offset","default":0},"limit":{"type":"integer","minimum":0,"title":"Limit","default":50},"total":{"type":"integer","minimum":0,"title":"Total","default":0}},"type":"object","title":"OffsetBasedPaginationResponse[EvalExperimentRowResponseV2]"},"OffsetBasedPaginationResponse_EvalExperimentSummaryResponseV2_":{"properties":{"response_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Response Code","description":"Machine-readable response code, when provided.","x-gitbook-description-html":"Machine-readable response code, when provided.
\n"},"meta":{"additionalProperties":true,"type":"object","title":"Meta","description":"Additional metadata","default":{},"x-gitbook-description-html":"Additional metadata
\n"},"data":{"items":{"$ref":"#/components/schemas/EvalExperimentSummaryResponseV2"},"type":"array","title":"Data"},"offset":{"type":"integer","minimum":0,"title":"Offset","default":0},"limit":{"type":"integer","minimum":0,"title":"Limit","default":50},"total":{"type":"integer","minimum":0,"title":"Total","default":0}},"type":"object","title":"OffsetBasedPaginationResponse[EvalExperimentSummaryResponseV2]"},"OffsetBasedPaginationResponse_EvalMonitorListItemResponseV2_":{"properties":{"response_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Response Code","description":"Machine-readable response code, when provided.","x-gitbook-description-html":"Machine-readable response code, when provided.
\n"},"meta":{"additionalProperties":true,"type":"object","title":"Meta","description":"Additional metadata","default":{},"x-gitbook-description-html":"Additional metadata
\n"},"data":{"items":{"$ref":"#/components/schemas/EvalMonitorListItemResponseV2"},"type":"array","title":"Data"},"offset":{"type":"integer","minimum":0,"title":"Offset","default":0},"limit":{"type":"integer","minimum":0,"title":"Limit","default":50},"total":{"type":"integer","minimum":0,"title":"Total","default":0}},"type":"object","title":"OffsetBasedPaginationResponse[EvalMonitorListItemResponseV2]"},"OffsetBasedPaginationResponse_EvaluatorResponseV2_":{"properties":{"response_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Response Code","description":"Machine-readable response code, when provided.","x-gitbook-description-html":"Machine-readable response code, when provided.
\n"},"meta":{"additionalProperties":true,"type":"object","title":"Meta","description":"Additional metadata","default":{},"x-gitbook-description-html":"Additional metadata
\n"},"data":{"items":{"$ref":"#/components/schemas/EvaluatorResponseV2"},"type":"array","title":"Data"},"offset":{"type":"integer","minimum":0,"title":"Offset","default":0},"limit":{"type":"integer","minimum":0,"title":"Limit","default":50},"total":{"type":"integer","minimum":0,"title":"Total","default":0}},"type":"object","title":"OffsetBasedPaginationResponse[EvaluatorResponseV2]"},"OffsetBasedPaginationResponse_ProviderActionSummaryResponseV2_":{"properties":{"response_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Response Code","description":"Machine-readable response code, when provided.","x-gitbook-description-html":"Machine-readable response code, when provided.
\n"},"meta":{"additionalProperties":true,"type":"object","title":"Meta","description":"Additional metadata","default":{},"x-gitbook-description-html":"Additional metadata
\n"},"data":{"items":{"$ref":"#/components/schemas/ProviderActionSummaryResponseV2"},"type":"array","title":"Data"},"offset":{"type":"integer","minimum":0,"title":"Offset","default":0},"limit":{"type":"integer","minimum":0,"title":"Limit","default":50},"total":{"type":"integer","minimum":0,"title":"Total","default":0}},"type":"object","title":"OffsetBasedPaginationResponse[ProviderActionSummaryResponseV2]"},"OffsetBasedPaginationResponse_ProviderResponseV2_":{"properties":{"response_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Response Code","description":"Machine-readable response code, when provided.","x-gitbook-description-html":"Machine-readable response code, when provided.
\n"},"meta":{"additionalProperties":true,"type":"object","title":"Meta","description":"Additional metadata","default":{},"x-gitbook-description-html":"Additional metadata
\n"},"data":{"items":{"$ref":"#/components/schemas/ProviderResponseV2"},"type":"array","title":"Data"},"offset":{"type":"integer","minimum":0,"title":"Offset","default":0},"limit":{"type":"integer","minimum":0,"title":"Limit","default":50},"total":{"type":"integer","minimum":0,"title":"Total","default":0}},"type":"object","title":"OffsetBasedPaginationResponse[ProviderResponseV2]"},"OffsetBasedPaginationResponse_ProviderTriggerSummaryResponseV2_":{"properties":{"response_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Response Code","description":"Machine-readable response code, when provided.","x-gitbook-description-html":"Machine-readable response code, when provided.
\n"},"meta":{"additionalProperties":true,"type":"object","title":"Meta","description":"Additional metadata","default":{},"x-gitbook-description-html":"Additional metadata
\n"},"data":{"items":{"$ref":"#/components/schemas/ProviderTriggerSummaryResponseV2"},"type":"array","title":"Data"},"offset":{"type":"integer","minimum":0,"title":"Offset","default":0},"limit":{"type":"integer","minimum":0,"title":"Limit","default":50},"total":{"type":"integer","minimum":0,"title":"Total","default":0}},"type":"object","title":"OffsetBasedPaginationResponse[ProviderTriggerSummaryResponseV2]"},"OffsetBasedPaginationResponse_SkillListItemResponseV2_":{"properties":{"response_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Response Code","description":"Machine-readable response code, when provided.","x-gitbook-description-html":"Machine-readable response code, when provided.
\n"},"meta":{"additionalProperties":true,"type":"object","title":"Meta","description":"Additional metadata","default":{},"x-gitbook-description-html":"Additional metadata
\n"},"data":{"items":{"$ref":"#/components/schemas/SkillListItemResponseV2"},"type":"array","title":"Data"},"offset":{"type":"integer","minimum":0,"title":"Offset","default":0},"limit":{"type":"integer","minimum":0,"title":"Limit","default":50},"total":{"type":"integer","minimum":0,"title":"Total","default":0}},"type":"object","title":"OffsetBasedPaginationResponse[SkillListItemResponseV2]"},"OffsetBasedPaginationResponse_SkillVersionListItemResponseV2_":{"properties":{"response_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Response Code","description":"Machine-readable response code, when provided.","x-gitbook-description-html":"Machine-readable response code, when provided.
\n"},"meta":{"additionalProperties":true,"type":"object","title":"Meta","description":"Additional metadata","default":{},"x-gitbook-description-html":"Additional metadata
\n"},"data":{"items":{"$ref":"#/components/schemas/SkillVersionListItemResponseV2"},"type":"array","title":"Data"},"offset":{"type":"integer","minimum":0,"title":"Offset","default":0},"limit":{"type":"integer","minimum":0,"title":"Limit","default":50},"total":{"type":"integer","minimum":0,"title":"Total","default":0}},"type":"object","title":"OffsetBasedPaginationResponse[SkillVersionListItemResponseV2]"},"OffsetBasedPaginationResponse_WebhookSubscriptionResponseV2_":{"properties":{"response_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Response Code","description":"Machine-readable response code, when provided.","x-gitbook-description-html":"Machine-readable response code, when provided.
\n"},"meta":{"additionalProperties":true,"type":"object","title":"Meta","description":"Additional metadata","default":{},"x-gitbook-description-html":"Additional metadata
\n"},"data":{"items":{"$ref":"#/components/schemas/WebhookSubscriptionResponseV2"},"type":"array","title":"Data"},"offset":{"type":"integer","minimum":0,"title":"Offset","default":0},"limit":{"type":"integer","minimum":0,"title":"Limit","default":50},"total":{"type":"integer","minimum":0,"title":"Total","default":0}},"type":"object","title":"OffsetBasedPaginationResponse[WebhookSubscriptionResponseV2]"},"PaginationDirection":{"type":"string","enum":["next","prev"],"title":"PaginationDirection","description":"Direction for cursor-based pagination.","x-gitbook-description-html":"Direction for cursor-based pagination.
\n"},"PauseContext":{"properties":{"run_id":{"type":"string","title":"Run Id"},"node_id":{"type":"string","title":"Node Id"},"question":{"type":"string","title":"Question","default":""},"context":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Context"},"response_type":{"type":"string","title":"Response Type","default":"text"},"choices":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Choices"},"resume_token":{"type":"string","title":"Resume Token"},"resume_endpoint":{"type":"string","title":"Resume Endpoint"},"expires_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Expires At","description":"When the resume token expires (decoded unverified for display; resume re-verifies).","readOnly":true,"x-gitbook-description-html":"When the resume token expires (decoded unverified for display; resume re-verifies).
\n"},"response_schema":{"additionalProperties":true,"type":"object","title":"Response Schema","description":"Minimal JSON Schema describing the answer this pause expects.","readOnly":true,"x-gitbook-description-html":"Minimal JSON Schema describing the answer this pause expects.
\n"}},"type":"object","required":["run_id","node_id","resume_token","resume_endpoint","expires_at","response_schema"],"title":"PauseContext","description":"What a paused run is waiting on, plus how to resume it.","x-gitbook-description-html":"What a paused run is waiting on, plus how to resume it.
\n"},"ProjectIoParameterResponseV2":{"properties":{"id":{"type":"string","title":"Id"},"name":{"type":"string","title":"Name"}},"type":"object","required":["id","name"],"title":"ProjectIoParameter"},"ProjectIoSchemaResponseV2":{"properties":{"input_kind":{"type":"string","enum":["start_node","legacy_input_nodes"],"title":"Input Kind"},"inputs":{"items":{"$ref":"#/components/schemas/ProjectIoParameterResponseV2"},"type":"array","title":"Inputs"},"outputs":{"items":{"$ref":"#/components/schemas/ProjectIoParameterResponseV2"},"type":"array","title":"Outputs"}},"type":"object","required":["input_kind","inputs","outputs"],"title":"ProjectIoSchema"},"ProjectRunSummary":{"properties":{"run_id":{"type":"string","format":"uuid","title":"Run Id"},"conversation_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Conversation Id"},"date":{"type":"string","format":"date-time","title":"Date"},"is_flow_successful":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Flow Successful"},"state":{"anyOf":[{"$ref":"#/components/schemas/WorkflowState"},{"type":"null"}]},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error"},"latency":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Latency"},"total_tokens":{"type":"integer","title":"Total Tokens"},"user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Id"},"inputs":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Inputs"},"outputs":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Outputs"},"llms":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Llms"},"feedback":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Feedback"},"cache_metrics":{"anyOf":[{"$ref":"#/components/schemas/CacheMetrics"},{"type":"null"}]},"llm_usage":{"items":{"$ref":"#/components/schemas/LLMUsageData"},"type":"array","title":"Llm Usage"},"run_type":{"anyOf":[{"$ref":"#/components/schemas/RunType"},{"type":"null"}],"description":"How the run was initiated.","x-gitbook-description-html":"How the run was initiated.
\n"},"ran_by_type":{"anyOf":[{"$ref":"#/components/schemas/RanByType"},{"type":"null"}],"description":"Who authenticated the run.","x-gitbook-description-html":"Who authenticated the run.
\n"},"ran_by_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ran By Id","description":"Principal the run is attributed to: profiles.id for user and personal_api_key (the key owner), organizations.org_id for org_api_key, end_users.id for end_user. NULL for system runs and legacy rows.","x-gitbook-description-html":"Principal the run is attributed to: profiles.id for user and personal_api_key (the key owner), organizations.org_id for org_api_key, end_users.id for end_user. NULL for system runs and legacy rows.
\n"},"ran_by_display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ran By Display Name","description":"Display name of the principal: the profile email for user and personal_api_key runs, the organization name for org_api_key runs.","x-gitbook-description-html":"Display name of the principal: the profile email for user and personal_api_key runs, the organization name for org_api_key runs.
\n"},"project_version_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Project Version Id","description":"Project version that executed the run. Non-positive values mean the draft.","x-gitbook-description-html":"Project version that executed the run. Non-positive values mean the draft.
\n"},"base_version_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Base Version Id","description":"For draft runs, the project's published version at run time. Lets the UI label a draft against the version it was based on (e.g. 'Draft (v3)').","x-gitbook-description-html":"For draft runs, the project's published version at run time. Lets the UI label a draft against the version it was based on (e.g. 'Draft (v3)').
\n"},"deployment_stage":{"anyOf":[{"$ref":"#/components/schemas/DeploymentStage"},{"type":"null"}],"description":"Stage the run executed against (draft/development/staging/production). Lets the UI tell a preview run (draft) from a deployed run for form and batch runs, which otherwise share the same project_version_id sentinel.","x-gitbook-description-html":"Stage the run executed against (draft/development/staging/production). Lets the UI tell a preview run (draft) from a deployed run for form and batch runs, which otherwise share the same project_version_id sentinel.
\n"},"parent_run_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Parent Run Id","description":"Run ID of the parent workflow for sub-workflow runs.","x-gitbook-description-html":"Run ID of the parent workflow for sub-workflow runs.
\n"},"parent_project_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Parent Project Id","description":"Project ID of the parent workflow for sub-workflow runs.","x-gitbook-description-html":"Project ID of the parent workflow for sub-workflow runs.
\n"},"parent_project_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Parent Project Name","description":"Name of the parent project for sub-workflow runs.","x-gitbook-description-html":"Name of the parent project for sub-workflow runs.
\n"}},"type":"object","required":["run_id","date","is_flow_successful","state","error","latency","total_tokens","user_id","inputs","outputs","llms","feedback"],"title":"ProjectRunSummary","description":"Summary of a single workflow run.","x-gitbook-description-html":"Summary of a single workflow run.
\n"},"ProviderActionInputParameterV2":{"properties":{"name":{"type":"string","title":"Name"},"type":{"$ref":"#/components/schemas/ProviderActionParameterTypeV2"},"label":{"type":"string","title":"Label"},"description":{"type":"string","title":"Description"},"required":{"type":"boolean","title":"Required","default":false},"default":{"title":"Default"},"options":{"items":{"$ref":"#/components/schemas/ProviderActionParameterOptionV2"},"type":"array","title":"Options"},"has_dynamic_options":{"type":"boolean","title":"Has Dynamic Options","default":false},"depends_on":{"items":{"type":"string"},"type":"array","title":"Depends On"},"minimum":{"anyOf":[{"type":"number"},{"type":"integer"},{"type":"null"}],"title":"Minimum"},"maximum":{"anyOf":[{"type":"number"},{"type":"integer"},{"type":"null"}],"title":"Maximum"}},"type":"object","required":["name","type","label","description"],"title":"ProviderActionInputParameter","description":"One input parameter of an action; `name` is the key used in the run `inputs` map.","x-gitbook-description-html":"One input parameter of an action; name is the key used in the run inputs map.
One output parameter of an action.
\n"},"ProviderActionParameterOptionV2":{"properties":{"value":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"number"},{"type":"boolean"}],"title":"Value"},"label":{"type":"string","title":"Label"}},"type":"object","required":["value","label"],"title":"ProviderActionParameterOption","description":"A selectable value for a parameter with a fixed choice list.","x-gitbook-description-html":"A selectable value for a parameter with a fixed choice list.
\n"},"ProviderActionParameterTypeV2":{"type":"string","enum":["string","number","integer","float","boolean","select","secret","secret_multiline","file","binary_file","files","knowledge_base","browser_navigation_replay","browser_navigation_session","connection","textline","textarea","multiple_select","string_array","number_array","date","time","datetime","percentage_slider","object","array","object_array","dict","dict_array","code","expression","file_picker","unknown"],"title":"ProviderActionParameterTypeV2","description":"The public parameter type.\n\nA StackAI-owned copy of the platform's parameter types, kept deliberately decoupled from the\ninternal engine enum (`stackflow`'s `ToolParameterType`) so the public contract does not\nshift when that internal enum changes. An internal type this copy does not list degrades to\n`UNKNOWN` rather than breaking the response.","x-gitbook-description-html":"The public parameter type.
\nA StackAI-owned copy of the platform's parameter types, kept deliberately decoupled from the\ninternal engine enum (stackflow's ToolParameterType) so the public contract does not\nshift when that internal enum changes. An internal type this copy does not list degrades to\nUNKNOWN rather than breaking the response.
A provider action on the public v2 catalog, with its input and output parameters.
\nServes the action-detail endpoint only. The parameters come from the provider cache — the\nsame snapshot as the rest of the catalog — not from a live registry crawl: the cache already\ncarries each action's flattened parameter metadata, so detail is a pure cache read. Output\nparameters are one level deep (nested object shapes surface as type: "object" without\ntheir sub-fields), which the cached representation does not expand.
A provider action's identity and metadata, without its input/output parameters.
\nServes the actions-list endpoint. A catalog list is intentionally lean — identity and\nmetadata to scan and pick from, not the full resource — matching how iPaaS platforms expose\naction catalogs (browse the list, then fetch one action for its fields). Callers fetch a\nsingle action's detail (ProviderActionResponseV2) for its input_parameters/output_parameters.
Deprecation metadata for a provider on the public v2 surface.
\n"},"ProviderResponseV2":{"properties":{"provider_id":{"type":"string","title":"Provider Id"},"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"},"icon_url":{"type":"string","title":"Icon Url"},"tags":{"items":{"type":"string"},"type":"array","title":"Tags"},"action_count":{"type":"integer","title":"Action Count","default":0},"trigger_count":{"type":"integer","title":"Trigger Count","default":0},"deprecation":{"anyOf":[{"$ref":"#/components/schemas/ProviderDeprecationV2"},{"type":"null"}]}},"type":"object","required":["provider_id","name","description","icon_url"],"title":"ProviderResponse","description":"An integration provider on the public v2 catalog. Serves both list and detail.","x-gitbook-description-html":"An integration provider on the public v2 catalog. Serves both list and detail.
\n"},"ProviderTriggerResponseV2":{"properties":{"trigger_id":{"type":"string","title":"Trigger Id"},"provider_id":{"type":"string","title":"Provider Id"},"trigger_type":{"$ref":"#/components/schemas/TriggerTypeV2"},"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"},"tags":{"items":{"type":"string"},"type":"array","title":"Tags"},"input_parameters":{"items":{"$ref":"#/components/schemas/ProviderActionInputParameterV2"},"type":"array","title":"Input Parameters"},"output_parameters":{"items":{"$ref":"#/components/schemas/ProviderActionOutputParameterV2"},"type":"array","title":"Output Parameters"}},"type":"object","required":["trigger_id","provider_id","trigger_type","name","description"],"title":"ProviderTriggerResponse","description":"A provider trigger on the public v2 catalog, with its cached parameters.","x-gitbook-description-html":"A provider trigger on the public v2 catalog, with its cached parameters.
\n"},"ProviderTriggerSummaryResponseV2":{"properties":{"trigger_id":{"type":"string","title":"Trigger Id"},"provider_id":{"type":"string","title":"Provider Id"},"trigger_type":{"$ref":"#/components/schemas/TriggerTypeV2"},"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"},"tags":{"items":{"type":"string"},"type":"array","title":"Tags"}},"type":"object","required":["trigger_id","provider_id","trigger_type","name","description"],"title":"ProviderTriggerSummaryResponse","description":"A provider trigger's identity and metadata, without its parameters.","x-gitbook-description-html":"A provider trigger's identity and metadata, without its parameters.
\n"},"RanByType":{"type":"string","enum":["user","personal_api_key","org_api_key","system","end_user"],"title":"RanByType","description":"Who or what authenticated the run.","x-gitbook-description-html":"Who or what authenticated the run.
\n"},"ResourceDownloadResponseV2":{"properties":{"download_url":{"type":"string","title":"Download Url","description":"Signed URL for direct download; expires.","x-gitbook-description-html":"Signed URL for direct download; expires.
\n"},"filename":{"type":"string","title":"Filename"}},"type":"object","required":["download_url","filename"],"title":"ResourceDownloadResponse","description":"A signed URL to download the original file.","x-gitbook-description-html":"A signed URL to download the original file.
\n"},"ResourceUploadResponse":{"properties":{"message":{"type":"string","title":"Message"},"resource_id":{"type":"string","format":"uuid","title":"Resource Id"}},"type":"object","required":["message","resource_id"],"title":"ResourceUploadResponse","description":"Result of a file upload, including the resource ID for status polling.","x-gitbook-description-html":"Result of a file upload, including the resource ID for status polling.
\n"},"ResourceUploadResponseV2":{"properties":{"message":{"type":"string","title":"Message"},"resource_id":{"type":"string","format":"uuid","title":"Resource Id"}},"type":"object","required":["message","resource_id"],"title":"ResourceUploadResponse","description":"Result of a file upload, including the resource ID for status polling.","x-gitbook-description-html":"Result of a file upload, including the resource ID for status polling.
\n"},"ResumeRunRequest":{"properties":{"resume_token":{"type":"string","title":"Resume Token"},"response":{"type":"string","title":"Response"},"response_type":{"anyOf":[{"$ref":"#/components/schemas/HitlResponseType"},{"type":"null"}],"description":"How to interpret `response`, mirroring the pause's `response_type`.","examples":["text","approval","choice"],"x-gitbook-description-html":"How to interpret response, mirroring the pause's response_type.
Request body to resume a paused run from the public API.
\n"},"RetrievalType":{"type":"string","enum":["docs","pages","chunks"],"title":"RetrievalType","description":"Retrieval type.","x-gitbook-description-html":"Retrieval type.
\n"},"RunCitationPositionV2":{"properties":{"page_index":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Page Index","description":"Zero-based page the chunk was read from, if recorded.","x-gitbook-description-html":"Zero-based page the chunk was read from, if recorded.
\n"},"chunk_index":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Chunk Index","description":"Zero-based index of the chunk within the source, if recorded.","x-gitbook-description-html":"Zero-based index of the chunk within the source, if recorded.
\n"},"page_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Page Number","description":"Page number as printed in the source, if known.","x-gitbook-description-html":"Page number as printed in the source, if known.
\n"}},"additionalProperties":false,"type":"object","required":["page_index","chunk_index","page_number"],"title":"RunCitationPosition","description":"Position of a citation within its source.","x-gitbook-description-html":"Position of a citation within its source.
\n"},"RunCitationSourceTypeV2":{"type":"string","enum":["knowledge_base","website","document","other"],"title":"RunCitationSourceTypeV2","description":"Type of source cited by the run.","x-gitbook-description-html":"Type of source cited by the run.
\n"},"RunCitationV2":{"properties":{"knowledge_base_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Knowledge Base Id","description":"Knowledge base the cited source belongs to, if any.","x-gitbook-description-html":"Knowledge base the cited source belongs to, if any.
\n"},"resource_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Resource Id","description":"Knowledge base resource that was cited, if any.","x-gitbook-description-html":"Knowledge base resource that was cited, if any.
\n"},"source_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Url","description":"External link to the cited source, if available.","x-gitbook-description-html":"External link to the cited source, if available.
\n"},"source_type":{"$ref":"#/components/schemas/RunCitationSourceTypeV2","description":"Kind of source that was cited.","x-gitbook-description-html":"Kind of source that was cited.
\n"},"position":{"anyOf":[{"$ref":"#/components/schemas/RunCitationPositionV2"},{"type":"null"}],"description":"Where in the source the cited chunk sits. Null when not recorded.","x-gitbook-description-html":"Where in the source the cited chunk sits. Null when not recorded.
\n"}},"additionalProperties":false,"type":"object","required":["knowledge_base_id","resource_id","source_url","source_type","position"],"title":"RunCitation","description":"Source cited by a run.","x-gitbook-description-html":"Source cited by a run.
\n"},"RunCreatedByTypeV2":{"type":"string","enum":["user","personal_api_key","org_api_key","system","end_user","unknown"],"title":"RunCreatedByTypeV2","description":"Type of user, API key, or system that started the run.","x-gitbook-description-html":"Type of user, API key, or system that started the run.
\n"},"RunCreatedByV2":{"properties":{"type":{"$ref":"#/components/schemas/RunCreatedByTypeV2","description":"Kind of principal that started the run.","x-gitbook-description-html":"Kind of principal that started the run.
\n"},"id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Id","description":"ID of the principal identified by `type`: the user ID for `user` and `personal_api_key`, the organization ID for `org_api_key`, the end-user ID for `end_user`. Null if no ID is available.","x-gitbook-description-html":"ID of the principal identified by type: the user ID for user and personal_api_key, the organization ID for org_api_key, the end-user ID for end_user. Null if no ID is available.
Who or what started the run.
\n"},"RunPauseResponseTypeV2":{"type":"string","enum":["text","approval","choice","unknown"],"title":"RunPauseResponseTypeV2","description":"Kind of answer requested by a paused ask-human step.","x-gitbook-description-html":"Kind of answer requested by a paused ask-human step.
\n"},"RunPendingInputV2":{"properties":{"question":{"type":"string","title":"Question","description":"Question shown to the human responder.","x-gitbook-description-html":"Question shown to the human responder.
\n"},"context":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Context","description":"Additional context, if supplied.","x-gitbook-description-html":"Additional context, if supplied.
\n"},"response_type":{"$ref":"#/components/schemas/RunPauseResponseTypeV2","description":"Expected answer kind.","x-gitbook-description-html":"Expected answer kind.
\n"},"choices":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Choices","description":"Ordered choices, when supplied.","x-gitbook-description-html":"Ordered choices, when supplied.
\n"},"resume_token":{"type":"string","title":"Resume Token","description":"Secret token authorizing this pause's resume.","x-gitbook-description-html":"Secret token authorizing this pause's resume.
\n"},"resume_token_expires_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Resume Token Expires At","description":"When the resume token expires; this is not the pause timeout.","x-gitbook-description-html":"When the resume token expires; this is not the pause timeout.
\n"}},"additionalProperties":false,"type":"object","required":["question","context","response_type","choices","resume_token","resume_token_expires_at"],"title":"RunPendingInput","description":"Ask-human input awaiting a response from a caller who may run the project.","x-gitbook-description-html":"Ask-human input awaiting a response from a caller who may run the project.
\n"},"RunProviderActionRequestV2":{"properties":{"connection_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Connection Id"},"inputs":{"additionalProperties":true,"type":"object","title":"Inputs"}},"additionalProperties":false,"type":"object","required":["inputs"],"title":"RunProviderActionRequest","description":"Body for running a provider action; `inputs` is validated against the action's own schema.","x-gitbook-description-html":"Body for running a provider action; inputs is validated against the action's own schema.
The result of running a provider action, keyed by the action's own output parameter names.
\n"},"RunResponseV2":{"properties":{"run_id":{"type":"string","format":"uuid","title":"Run Id","description":"ID of the run.","x-gitbook-description-html":"ID of the run.
\n"},"project_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Project Id","description":"Project the run executed. Null for legacy runs.","x-gitbook-description-html":"Project the run executed. Null for legacy runs.
\n"},"project_version":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Project Version","description":"Project version used for this run: -1 for a draft execution, a non-negative integer for a numbered version, or null when the version could not be determined.","x-gitbook-description-html":"Project version used for this run: -1 for a draft execution, a non-negative integer for a numbered version, or null when the version could not be determined.
\n"},"status":{"$ref":"#/components/schemas/RunStatusV2","description":"Lifecycle status of the run.","x-gitbook-description-html":"Lifecycle status of the run.
\n"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"Failure message. Null when the run did not fail.","x-gitbook-description-html":"Failure message. Null when the run did not fail.
\n"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When the run was recorded.","x-gitbook-description-html":"When the run was recorded.
\n"},"started_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Started At","description":"When execution started. Null when unknown or not yet started.","x-gitbook-description-html":"When execution started. Null when unknown or not yet started.
\n"},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Completed At","description":"When execution finished. Null when unknown or not yet finished.","x-gitbook-description-html":"When execution finished. Null when unknown or not yet finished.
\n"},"run_type":{"anyOf":[{"$ref":"#/components/schemas/RunTypeV2"},{"type":"null"}],"description":"How the run was started. Null when not recorded.","x-gitbook-description-html":"How the run was started. Null when not recorded.
\n"},"created_by":{"anyOf":[{"$ref":"#/components/schemas/RunCreatedByV2"},{"type":"null"}],"description":"Principal that started the run. Null when not recorded.","x-gitbook-description-html":"Principal that started the run. Null when not recorded.
\n"},"usage":{"$ref":"#/components/schemas/RunUsageV2","description":"Token usage for the run.","x-gitbook-description-html":"Token usage for the run.
\n"},"parent_run_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Parent Run Id","description":"Run that started this one. Null unless this is a sub-workflow run.","x-gitbook-description-html":"Run that started this one. Null unless this is a sub-workflow run.
\n"},"parent_project_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Parent Project Id","description":"Project of the parent run. Null unless this is a sub-workflow run.","x-gitbook-description-html":"Project of the parent run. Null unless this is a sub-workflow run.
\n"},"input":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Input","description":"Inputs the run was started with.","x-gitbook-description-html":"Inputs the run was started with.
\n"},"output":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Output","description":"Outputs the run produced.","x-gitbook-description-html":"Outputs the run produced.
\n"},"citations":{"anyOf":[{"items":{"$ref":"#/components/schemas/RunCitationV2"},"type":"array"},{"type":"null"}],"title":"Citations","description":"Sources cited by the run. Null when the run recorded none.","x-gitbook-description-html":"Sources cited by the run. Null when the run recorded none.
\n"},"pending_input":{"anyOf":[{"$ref":"#/components/schemas/RunPendingInputV2"},{"type":"null"}],"description":"Ask-human input for a paused run. Null unless the caller can both read and resume it.","x-gitbook-description-html":"Ask-human input for a paused run. Null unless the caller can both read and resume it.
\n"}},"additionalProperties":false,"type":"object","required":["run_id","project_id","status","error","created_at","started_at","completed_at","run_type","created_by","usage","parent_run_id","parent_project_id","input","output","citations","pending_input"],"title":"RunResponse","description":"A run with its input, output, citations, and token usage.","x-gitbook-description-html":"A run with its input, output, citations, and token usage.
\n"},"RunResumeRequestV2":{"properties":{"resume_token":{"type":"string","title":"Resume Token","description":"Token issued for the paused ask-human step.","x-gitbook-description-html":"Token issued for the paused ask-human step.
\n"},"response":{"type":"string","title":"Response","description":"Human response to the paused step.","x-gitbook-description-html":"Human response to the paused step.
\n"},"response_type":{"anyOf":[{"$ref":"#/components/schemas/RunResumeResponseTypeV2"},{"type":"null"}],"description":"How to interpret the response; defaults to text when omitted.","x-gitbook-description-html":"How to interpret the response; defaults to text when omitted.
\n"}},"additionalProperties":false,"type":"object","required":["resume_token","response"],"title":"RunResumeRequest","description":"Body for resuming an ask-human pause.","x-gitbook-description-html":"Body for resuming an ask-human pause.
\n"},"RunResumeResponseTypeV2":{"type":"string","enum":["text","approval","choice"],"title":"RunResumeResponseTypeV2","description":"Kind of answer sent to a paused ask-human step.","x-gitbook-description-html":"Kind of answer sent to a paused ask-human step.
\n"},"RunStartRequestV2":{"properties":{"project_id":{"type":"string","title":"Project Id"},"input":{"additionalProperties":true,"type":"object","title":"Input","description":"Node inputs keyed by node id, matching the project's input schema.","x-gitbook-description-html":"Node inputs keyed by node id, matching the project's input schema.
\n"},"project_version":{"anyOf":[{"type":"integer","minimum":-1},{"type":"null"}],"title":"Project Version","description":"Project version to run. Omit or use null for the current published version, use -1 for the current draft, or use a non-negative version for an exact snapshot.","x-gitbook-description-html":"Project version to run. Omit or use null for the current published version, use -1 for the current draft, or use a non-negative version for an exact snapshot.
\n"}},"additionalProperties":false,"type":"object","required":["project_id","input"],"title":"RunStartRequest","description":"Body for starting a project run.","x-gitbook-description-html":"Body for starting a project run.
\n"},"RunStatusResponse":{"properties":{"run_id":{"type":"string","title":"Run Id"},"state":{"anyOf":[{"$ref":"#/components/schemas/WorkflowState"},{"type":"null"}]},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error"},"pause":{"anyOf":[{"$ref":"#/components/schemas/PauseContext"},{"type":"null"}]}},"type":"object","required":["run_id"],"title":"RunStatusResponse","description":"Public run status, surfacing the pause context when the run is awaiting a response.","x-gitbook-description-html":"Public run status, surfacing the pause context when the run is awaiting a response.
\n"},"RunStatusV2":{"type":"string","enum":["queued","running","paused","succeeded","failed","cancelled"],"title":"RunStatusV2","description":"Lifecycle status exposed by the Runs v2 API.","x-gitbook-description-html":"Lifecycle status exposed by the Runs v2 API.
\n"},"RunSummaryResponseV2":{"properties":{"run_id":{"type":"string","format":"uuid","title":"Run Id","description":"ID of the run.","x-gitbook-description-html":"ID of the run.
\n"},"project_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Project Id","description":"Project the run executed. Null for legacy runs.","x-gitbook-description-html":"Project the run executed. Null for legacy runs.
\n"},"project_version":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Project Version","description":"Project version used for this run: -1 for a draft execution, a non-negative integer for a numbered version, or null when the version could not be determined.","x-gitbook-description-html":"Project version used for this run: -1 for a draft execution, a non-negative integer for a numbered version, or null when the version could not be determined.
\n"},"status":{"$ref":"#/components/schemas/RunStatusV2","description":"Lifecycle status of the run.","x-gitbook-description-html":"Lifecycle status of the run.
\n"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"Failure message. Null when the run did not fail.","x-gitbook-description-html":"Failure message. Null when the run did not fail.
\n"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When the run was recorded.","x-gitbook-description-html":"When the run was recorded.
\n"},"started_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Started At","description":"When execution started. Null when unknown or not yet started.","x-gitbook-description-html":"When execution started. Null when unknown or not yet started.
\n"},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Completed At","description":"When execution finished. Null when unknown or not yet finished.","x-gitbook-description-html":"When execution finished. Null when unknown or not yet finished.
\n"},"run_type":{"anyOf":[{"$ref":"#/components/schemas/RunTypeV2"},{"type":"null"}],"description":"How the run was started. Null when not recorded.","x-gitbook-description-html":"How the run was started. Null when not recorded.
\n"},"created_by":{"anyOf":[{"$ref":"#/components/schemas/RunCreatedByV2"},{"type":"null"}],"description":"Principal that started the run. Null when not recorded.","x-gitbook-description-html":"Principal that started the run. Null when not recorded.
\n"},"usage":{"$ref":"#/components/schemas/RunUsageV2","description":"Token usage for the run.","x-gitbook-description-html":"Token usage for the run.
\n"},"parent_run_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Parent Run Id","description":"Run that started this one. Null unless this is a sub-workflow run.","x-gitbook-description-html":"Run that started this one. Null unless this is a sub-workflow run.
\n"},"parent_project_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Parent Project Id","description":"Project of the parent run. Null unless this is a sub-workflow run.","x-gitbook-description-html":"Project of the parent run. Null unless this is a sub-workflow run.
\n"}},"additionalProperties":false,"type":"object","required":["run_id","project_id","status","error","created_at","started_at","completed_at","run_type","created_by","usage","parent_run_id","parent_project_id"],"title":"RunSummaryResponse","description":"A list row without its unbounded input, output, or citations.","x-gitbook-description-html":"A list row without its unbounded input, output, or citations.
\n"},"RunType":{"type":"string","enum":["workflow_builder","form","batch","chat_assistant","agent_assistant","trigger","scheduled","sub_workflow","api","eval"],"title":"RunType","description":"How a workflow run was initiated.","x-gitbook-description-html":"How a workflow run was initiated.
\n"},"RunTypeV2":{"type":"string","enum":["workflow_builder","form","batch","chat_assistant","agent_assistant","trigger","scheduled","sub_workflow","api","eval","unknown"],"title":"RunTypeV2","description":"How the run was started. Unrecognized types appear as `unknown`.","x-gitbook-description-html":"How the run was started. Unrecognized types appear as unknown.
Stable lowercase identifier of the model provider, e.g. openai.
Identifier of the model the provider was called with.
\n"},"connection_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Connection Id","description":"ID of the connection used for the model calls. Null if no connection ID is available.","x-gitbook-description-html":"ID of the connection used for the model calls. Null if no connection ID is available.
\n"},"input_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Input Tokens","description":"Tokens sent to the model. Null when the provider reported only a total.","x-gitbook-description-html":"Tokens sent to the model. Null when the provider reported only a total.
\n"},"output_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Output Tokens","description":"Tokens returned by the model. Null when the provider reported only a total.","x-gitbook-description-html":"Tokens returned by the model. Null when the provider reported only a total.
\n"}},"additionalProperties":false,"type":"object","required":["provider","model_id","connection_id","input_tokens","output_tokens"],"title":"RunUsageDetail","description":"Token usage for one provider, model, and connection.","x-gitbook-description-html":"Token usage for one provider, model, and connection.
\n"},"RunUsageV2":{"properties":{"total_tokens":{"type":"integer","title":"Total Tokens","description":"Tokens used across every model call in the run.","x-gitbook-description-html":"Tokens used across every model call in the run.
\n"},"details":{"items":{"$ref":"#/components/schemas/RunUsageDetailV2"},"type":"array","title":"Details","description":"Usage aggregated per model and connection; models may appear more than once.","x-gitbook-description-html":"Usage aggregated per model and connection; models may appear more than once.
\n"}},"additionalProperties":false,"type":"object","required":["total_tokens","details"],"title":"RunUsage","description":"Total and per-model token usage for a run.","x-gitbook-description-html":"Total and per-model token usage for a run.
\n"},"SelectedWebsiteSource":{"properties":{"source_type":{"$ref":"#/components/schemas/SelectedWebsiteSourceType","default":"sitemap"},"original_search_term":{"type":"string","title":"Original Search Term"},"selected_resources":{"items":{"type":"string"},"type":"array","title":"Selected Resources"}},"type":"object","required":["original_search_term","selected_resources"],"title":"SelectedWebsiteSource","description":"A set of pages selected for indexing from a website source.","x-gitbook-description-html":"A set of pages selected for indexing from a website source.
\n"},"SelectedWebsiteSourceType":{"type":"string","enum":["sitemap","manual"],"title":"SelectedWebsiteSourceType","description":"The type of website source.","x-gitbook-description-html":"The type of website source.
\n"},"SkillCreatorResponseV2":{"properties":{"id":{"type":"string","title":"Id"},"full_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Full Name"}},"type":"object","required":["id","full_name"],"title":"SkillCreatorResponse"},"SkillFileResponseV2":{"properties":{"path":{"type":"string","title":"Path"},"content_type":{"type":"string","title":"Content Type"},"size":{"type":"integer","title":"Size"}},"type":"object","required":["path","content_type","size"],"title":"SkillFileResponse"},"SkillListItemResponseV2":{"properties":{"skill_id":{"type":"string","format":"uuid","title":"Skill Id"},"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"},"version":{"type":"integer","title":"Version"},"is_builtin":{"type":"boolean","title":"Is Builtin"},"actions":{"items":{"type":"string"},"type":"array","title":"Actions"},"created_by_user_profile":{"anyOf":[{"$ref":"#/components/schemas/SkillCreatorResponseV2"},{"type":"null"}]},"created_by_org":{"$ref":"#/components/schemas/SkillOrganizationResponseV2"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At"}},"type":"object","required":["skill_id","name","description","version","is_builtin","actions","created_by_user_profile","created_by_org","created_at","updated_at"],"title":"SkillListItemResponse"},"SkillOrganizationResponseV2":{"properties":{"org_id":{"type":"string","title":"Org Id"},"org_name":{"type":"string","title":"Org Name"}},"type":"object","required":["org_id","org_name"],"title":"SkillOrganizationResponse"},"SkillResponseV2":{"properties":{"skill_id":{"type":"string","format":"uuid","title":"Skill Id"},"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"},"version":{"type":"integer","title":"Version"},"is_builtin":{"type":"boolean","title":"Is Builtin"},"actions":{"items":{"type":"string"},"type":"array","title":"Actions"},"created_by_user_profile":{"anyOf":[{"$ref":"#/components/schemas/SkillCreatorResponseV2"},{"type":"null"}]},"created_by_org":{"$ref":"#/components/schemas/SkillOrganizationResponseV2"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At"},"instructions":{"type":"string","title":"Instructions"},"frontmatter":{"additionalProperties":true,"type":"object","title":"Frontmatter"},"files":{"items":{"$ref":"#/components/schemas/SkillFileResponseV2"},"type":"array","title":"Files"}},"type":"object","required":["skill_id","name","description","version","is_builtin","actions","created_by_user_profile","created_by_org","created_at","updated_at","instructions"],"title":"SkillResponse"},"SkillVersionListItemResponseV2":{"properties":{"version":{"type":"integer","title":"Version"},"description":{"type":"string","title":"Description"},"created_by_user_profile":{"anyOf":[{"$ref":"#/components/schemas/SkillCreatorResponseV2"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time","title":"Created At"}},"type":"object","required":["version","description","created_by_user_profile","created_at"],"title":"SkillVersionListItemResponse"},"SkillVersionResponseV2":{"properties":{"version":{"type":"integer","title":"Version"},"description":{"type":"string","title":"Description"},"created_by_user_profile":{"anyOf":[{"$ref":"#/components/schemas/SkillCreatorResponseV2"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time","title":"Created At"},"instructions":{"type":"string","title":"Instructions"},"frontmatter":{"additionalProperties":true,"type":"object","title":"Frontmatter"},"actions":{"items":{"type":"string"},"type":"array","title":"Actions"},"files":{"items":{"$ref":"#/components/schemas/SkillFileResponseV2"},"type":"array","title":"Files"}},"type":"object","required":["version","description","created_by_user_profile","created_at","instructions"],"title":"SkillVersionResponse"},"StackAIAPIDataResponse_EvalDatasetResponseV2_":{"properties":{"response_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Response Code","description":"Machine-readable response code, when provided.","x-gitbook-description-html":"Machine-readable response code, when provided.
\n"},"meta":{"additionalProperties":true,"type":"object","title":"Meta","description":"Additional metadata","default":{},"x-gitbook-description-html":"Additional metadata
\n"},"data":{"$ref":"#/components/schemas/EvalDatasetResponseV2","description":"Data returned by the API service","x-gitbook-description-html":"Data returned by the API service
\n"}},"type":"object","required":["data"],"title":"StackAIAPIDataResponse[EvalDatasetResponseV2]"},"StackAIAPIDataResponse_EvalDatasetRowResponseV2_":{"properties":{"response_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Response Code","description":"Machine-readable response code, when provided.","x-gitbook-description-html":"Machine-readable response code, when provided.
\n"},"meta":{"additionalProperties":true,"type":"object","title":"Meta","description":"Additional metadata","default":{},"x-gitbook-description-html":"Additional metadata
\n"},"data":{"$ref":"#/components/schemas/EvalDatasetRowResponseV2","description":"Data returned by the API service","x-gitbook-description-html":"Data returned by the API service
\n"}},"type":"object","required":["data"],"title":"StackAIAPIDataResponse[EvalDatasetRowResponseV2]"},"StackAIAPIDataResponse_EvalExperimentCreateResponseV2_":{"properties":{"response_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Response Code","description":"Machine-readable response code, when provided.","x-gitbook-description-html":"Machine-readable response code, when provided.
\n"},"meta":{"additionalProperties":true,"type":"object","title":"Meta","description":"Additional metadata","default":{},"x-gitbook-description-html":"Additional metadata
\n"},"data":{"$ref":"#/components/schemas/EvalExperimentCreateResponseV2","description":"Data returned by the API service","x-gitbook-description-html":"Data returned by the API service
\n"}},"type":"object","required":["data"],"title":"StackAIAPIDataResponse[EvalExperimentCreateResponseV2]"},"StackAIAPIDataResponse_EvalExperimentDetailResponseV2_":{"properties":{"response_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Response Code","description":"Machine-readable response code, when provided.","x-gitbook-description-html":"Machine-readable response code, when provided.
\n"},"meta":{"additionalProperties":true,"type":"object","title":"Meta","description":"Additional metadata","default":{},"x-gitbook-description-html":"Additional metadata
\n"},"data":{"$ref":"#/components/schemas/EvalExperimentDetailResponseV2","description":"Data returned by the API service","x-gitbook-description-html":"Data returned by the API service
\n"}},"type":"object","required":["data"],"title":"StackAIAPIDataResponse[EvalExperimentDetailResponseV2]"},"StackAIAPIDataResponse_EvalExperimentJobAcceptedResponseV2_":{"properties":{"response_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Response Code","description":"Machine-readable response code, when provided.","x-gitbook-description-html":"Machine-readable response code, when provided.
\n"},"meta":{"additionalProperties":true,"type":"object","title":"Meta","description":"Additional metadata","default":{},"x-gitbook-description-html":"Additional metadata
\n"},"data":{"$ref":"#/components/schemas/EvalExperimentJobAcceptedResponseV2","description":"Data returned by the API service","x-gitbook-description-html":"Data returned by the API service
\n"}},"type":"object","required":["data"],"title":"StackAIAPIDataResponse[EvalExperimentJobAcceptedResponseV2]"},"StackAIAPIDataResponse_EvalExperimentJobResponseV2_":{"properties":{"response_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Response Code","description":"Machine-readable response code, when provided.","x-gitbook-description-html":"Machine-readable response code, when provided.
\n"},"meta":{"additionalProperties":true,"type":"object","title":"Meta","description":"Additional metadata","default":{},"x-gitbook-description-html":"Additional metadata
\n"},"data":{"$ref":"#/components/schemas/EvalExperimentJobResponseV2","description":"Data returned by the API service","x-gitbook-description-html":"Data returned by the API service
\n"}},"type":"object","required":["data"],"title":"StackAIAPIDataResponse[EvalExperimentJobResponseV2]"},"StackAIAPIDataResponse_EvalExperimentResponseV2_":{"properties":{"response_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Response Code","description":"Machine-readable response code, when provided.","x-gitbook-description-html":"Machine-readable response code, when provided.
\n"},"meta":{"additionalProperties":true,"type":"object","title":"Meta","description":"Additional metadata","default":{},"x-gitbook-description-html":"Additional metadata
\n"},"data":{"$ref":"#/components/schemas/EvalExperimentResponseV2","description":"Data returned by the API service","x-gitbook-description-html":"Data returned by the API service
\n"}},"type":"object","required":["data"],"title":"StackAIAPIDataResponse[EvalExperimentResponseV2]"},"StackAIAPIDataResponse_EvalExperimentStatusResponseV2_":{"properties":{"response_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Response Code","description":"Machine-readable response code, when provided.","x-gitbook-description-html":"Machine-readable response code, when provided.
\n"},"meta":{"additionalProperties":true,"type":"object","title":"Meta","description":"Additional metadata","default":{},"x-gitbook-description-html":"Additional metadata
\n"},"data":{"$ref":"#/components/schemas/EvalExperimentStatusResponseV2","description":"Data returned by the API service","x-gitbook-description-html":"Data returned by the API service
\n"}},"type":"object","required":["data"],"title":"StackAIAPIDataResponse[EvalExperimentStatusResponseV2]"},"StackAIAPIDataResponse_EvalMonitorAlertResponseV2_":{"properties":{"response_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Response Code","description":"Machine-readable response code, when provided.","x-gitbook-description-html":"Machine-readable response code, when provided.
\n"},"meta":{"additionalProperties":true,"type":"object","title":"Meta","description":"Additional metadata","default":{},"x-gitbook-description-html":"Additional metadata
\n"},"data":{"$ref":"#/components/schemas/EvalMonitorAlertResponseV2","description":"Data returned by the API service","x-gitbook-description-html":"Data returned by the API service
\n"}},"type":"object","required":["data"],"title":"StackAIAPIDataResponse[EvalMonitorAlertResponseV2]"},"StackAIAPIDataResponse_EvalMonitorLimitsResponseV2_":{"properties":{"response_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Response Code","description":"Machine-readable response code, when provided.","x-gitbook-description-html":"Machine-readable response code, when provided.
\n"},"meta":{"additionalProperties":true,"type":"object","title":"Meta","description":"Additional metadata","default":{},"x-gitbook-description-html":"Additional metadata
\n"},"data":{"$ref":"#/components/schemas/EvalMonitorLimitsResponseV2","description":"Data returned by the API service","x-gitbook-description-html":"Data returned by the API service
\n"}},"type":"object","required":["data"],"title":"StackAIAPIDataResponse[EvalMonitorLimitsResponseV2]"},"StackAIAPIDataResponse_EvalMonitorResponseV2_":{"properties":{"response_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Response Code","description":"Machine-readable response code, when provided.","x-gitbook-description-html":"Machine-readable response code, when provided.
\n"},"meta":{"additionalProperties":true,"type":"object","title":"Meta","description":"Additional metadata","default":{},"x-gitbook-description-html":"Additional metadata
\n"},"data":{"$ref":"#/components/schemas/EvalMonitorResponseV2","description":"Data returned by the API service","x-gitbook-description-html":"Data returned by the API service
\n"}},"type":"object","required":["data"],"title":"StackAIAPIDataResponse[EvalMonitorResponseV2]"},"StackAIAPIDataResponse_EvalMonitorScoreStatsResponseV2_":{"properties":{"response_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Response Code","description":"Machine-readable response code, when provided.","x-gitbook-description-html":"Machine-readable response code, when provided.
\n"},"meta":{"additionalProperties":true,"type":"object","title":"Meta","description":"Additional metadata","default":{},"x-gitbook-description-html":"Additional metadata
\n"},"data":{"$ref":"#/components/schemas/EvalMonitorScoreStatsResponseV2","description":"Data returned by the API service","x-gitbook-description-html":"Data returned by the API service
\n"}},"type":"object","required":["data"],"title":"StackAIAPIDataResponse[EvalMonitorScoreStatsResponseV2]"},"StackAIAPIDataResponse_EvalRunScoreResponseV2_":{"properties":{"response_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Response Code","description":"Machine-readable response code, when provided.","x-gitbook-description-html":"Machine-readable response code, when provided.
\n"},"meta":{"additionalProperties":true,"type":"object","title":"Meta","description":"Additional metadata","default":{},"x-gitbook-description-html":"Additional metadata
\n"},"data":{"$ref":"#/components/schemas/EvalRunScoreResponseV2","description":"Data returned by the API service","x-gitbook-description-html":"Data returned by the API service
\n"}},"type":"object","required":["data"],"title":"StackAIAPIDataResponse[EvalRunScoreResponseV2]"},"StackAIAPIDataResponse_EvaluatorResponseV2_":{"properties":{"response_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Response Code","description":"Machine-readable response code, when provided.","x-gitbook-description-html":"Machine-readable response code, when provided.
\n"},"meta":{"additionalProperties":true,"type":"object","title":"Meta","description":"Additional metadata","default":{},"x-gitbook-description-html":"Additional metadata
\n"},"data":{"$ref":"#/components/schemas/EvaluatorResponseV2","description":"Data returned by the API service","x-gitbook-description-html":"Data returned by the API service
\n"}},"type":"object","required":["data"],"title":"StackAIAPIDataResponse[EvaluatorResponseV2]"},"StackAIAPIDataResponse_KnowledgeBaseFileResponseV2_":{"properties":{"response_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Response Code","description":"Machine-readable response code, when provided.","x-gitbook-description-html":"Machine-readable response code, when provided.
\n"},"meta":{"additionalProperties":true,"type":"object","title":"Meta","description":"Additional metadata","default":{},"x-gitbook-description-html":"Additional metadata
\n"},"data":{"$ref":"#/components/schemas/KnowledgeBaseFileResponseV2","description":"Data returned by the API service","x-gitbook-description-html":"Data returned by the API service
\n"}},"type":"object","required":["data"],"title":"StackAIAPIDataResponse[KnowledgeBaseFileResponseV2]"},"StackAIAPIDataResponse_KnowledgeBaseMetadataSchemasResponseV2_":{"properties":{"response_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Response Code","description":"Machine-readable response code, when provided.","x-gitbook-description-html":"Machine-readable response code, when provided.
\n"},"meta":{"additionalProperties":true,"type":"object","title":"Meta","description":"Additional metadata","default":{},"x-gitbook-description-html":"Additional metadata
\n"},"data":{"$ref":"#/components/schemas/KnowledgeBaseMetadataSchemasResponseV2","description":"Data returned by the API service","x-gitbook-description-html":"Data returned by the API service
\n"}},"type":"object","required":["data"],"title":"StackAIAPIDataResponse[KnowledgeBaseMetadataSchemasResponseV2]"},"StackAIAPIDataResponse_KnowledgeBaseResponseV2_":{"properties":{"response_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Response Code","description":"Machine-readable response code, when provided.","x-gitbook-description-html":"Machine-readable response code, when provided.
\n"},"meta":{"additionalProperties":true,"type":"object","title":"Meta","description":"Additional metadata","default":{},"x-gitbook-description-html":"Additional metadata
\n"},"data":{"$ref":"#/components/schemas/KnowledgeBaseResponseV2","description":"Data returned by the API service","x-gitbook-description-html":"Data returned by the API service
\n"}},"type":"object","required":["data"],"title":"StackAIAPIDataResponse[KnowledgeBaseResponseV2]"},"StackAIAPIDataResponse_KnowledgeBaseSyncResponseV2_":{"properties":{"response_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Response Code","description":"Machine-readable response code, when provided.","x-gitbook-description-html":"Machine-readable response code, when provided.
\n"},"meta":{"additionalProperties":true,"type":"object","title":"Meta","description":"Additional metadata","default":{},"x-gitbook-description-html":"Additional metadata
\n"},"data":{"$ref":"#/components/schemas/KnowledgeBaseSyncResponseV2","description":"Data returned by the API service","x-gitbook-description-html":"Data returned by the API service
\n"}},"type":"object","required":["data"],"title":"StackAIAPIDataResponse[KnowledgeBaseSyncResponseV2]"},"StackAIAPIDataResponse_ProjectIoSchemaResponseV2_":{"properties":{"response_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Response Code","description":"Machine-readable response code, when provided.","x-gitbook-description-html":"Machine-readable response code, when provided.
\n"},"meta":{"additionalProperties":true,"type":"object","title":"Meta","description":"Additional metadata","default":{},"x-gitbook-description-html":"Additional metadata
\n"},"data":{"$ref":"#/components/schemas/ProjectIoSchemaResponseV2","description":"Data returned by the API service","x-gitbook-description-html":"Data returned by the API service
\n"}},"type":"object","required":["data"],"title":"StackAIAPIDataResponse[ProjectIoSchemaResponseV2]"},"StackAIAPIDataResponse_ProviderActionResponseV2_":{"properties":{"response_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Response Code","description":"Machine-readable response code, when provided.","x-gitbook-description-html":"Machine-readable response code, when provided.
\n"},"meta":{"additionalProperties":true,"type":"object","title":"Meta","description":"Additional metadata","default":{},"x-gitbook-description-html":"Additional metadata
\n"},"data":{"$ref":"#/components/schemas/ProviderActionResponseV2","description":"Data returned by the API service","x-gitbook-description-html":"Data returned by the API service
\n"}},"type":"object","required":["data"],"title":"StackAIAPIDataResponse[ProviderActionResponseV2]"},"StackAIAPIDataResponse_ProviderResponseV2_":{"properties":{"response_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Response Code","description":"Machine-readable response code, when provided.","x-gitbook-description-html":"Machine-readable response code, when provided.
\n"},"meta":{"additionalProperties":true,"type":"object","title":"Meta","description":"Additional metadata","default":{},"x-gitbook-description-html":"Additional metadata
\n"},"data":{"$ref":"#/components/schemas/ProviderResponseV2","description":"Data returned by the API service","x-gitbook-description-html":"Data returned by the API service
\n"}},"type":"object","required":["data"],"title":"StackAIAPIDataResponse[ProviderResponseV2]"},"StackAIAPIDataResponse_ProviderTriggerResponseV2_":{"properties":{"response_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Response Code","description":"Machine-readable response code, when provided.","x-gitbook-description-html":"Machine-readable response code, when provided.
\n"},"meta":{"additionalProperties":true,"type":"object","title":"Meta","description":"Additional metadata","default":{},"x-gitbook-description-html":"Additional metadata
\n"},"data":{"$ref":"#/components/schemas/ProviderTriggerResponseV2","description":"Data returned by the API service","x-gitbook-description-html":"Data returned by the API service
\n"}},"type":"object","required":["data"],"title":"StackAIAPIDataResponse[ProviderTriggerResponseV2]"},"StackAIAPIDataResponse_ResourceDownloadResponseV2_":{"properties":{"response_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Response Code","description":"Machine-readable response code, when provided.","x-gitbook-description-html":"Machine-readable response code, when provided.
\n"},"meta":{"additionalProperties":true,"type":"object","title":"Meta","description":"Additional metadata","default":{},"x-gitbook-description-html":"Additional metadata
\n"},"data":{"$ref":"#/components/schemas/ResourceDownloadResponseV2","description":"Data returned by the API service","x-gitbook-description-html":"Data returned by the API service
\n"}},"type":"object","required":["data"],"title":"StackAIAPIDataResponse[ResourceDownloadResponseV2]"},"StackAIAPIDataResponse_ResourceUploadResponseV2_":{"properties":{"response_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Response Code","description":"Machine-readable response code, when provided.","x-gitbook-description-html":"Machine-readable response code, when provided.
\n"},"meta":{"additionalProperties":true,"type":"object","title":"Meta","description":"Additional metadata","default":{},"x-gitbook-description-html":"Additional metadata
\n"},"data":{"$ref":"#/components/schemas/ResourceUploadResponseV2","description":"Data returned by the API service","x-gitbook-description-html":"Data returned by the API service
\n"}},"type":"object","required":["data"],"title":"StackAIAPIDataResponse[ResourceUploadResponseV2]"},"StackAIAPIDataResponse_RunProviderActionResponseV2_":{"properties":{"response_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Response Code","description":"Machine-readable response code, when provided.","x-gitbook-description-html":"Machine-readable response code, when provided.
\n"},"meta":{"additionalProperties":true,"type":"object","title":"Meta","description":"Additional metadata","default":{},"x-gitbook-description-html":"Additional metadata
\n"},"data":{"$ref":"#/components/schemas/RunProviderActionResponseV2","description":"Data returned by the API service","x-gitbook-description-html":"Data returned by the API service
\n"}},"type":"object","required":["data"],"title":"StackAIAPIDataResponse[RunProviderActionResponseV2]"},"StackAIAPIDataResponse_RunResponseV2_":{"properties":{"response_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Response Code","description":"Machine-readable response code, when provided.","x-gitbook-description-html":"Machine-readable response code, when provided.
\n"},"meta":{"additionalProperties":true,"type":"object","title":"Meta","description":"Additional metadata","default":{},"x-gitbook-description-html":"Additional metadata
\n"},"data":{"$ref":"#/components/schemas/RunResponseV2","description":"Data returned by the API service","x-gitbook-description-html":"Data returned by the API service
\n"}},"type":"object","required":["data"],"title":"StackAIAPIDataResponse[RunResponseV2]"},"StackAIAPIDataResponse_SkillResponseV2_":{"properties":{"response_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Response Code","description":"Machine-readable response code, when provided.","x-gitbook-description-html":"Machine-readable response code, when provided.
\n"},"meta":{"additionalProperties":true,"type":"object","title":"Meta","description":"Additional metadata","default":{},"x-gitbook-description-html":"Additional metadata
\n"},"data":{"$ref":"#/components/schemas/SkillResponseV2","description":"Data returned by the API service","x-gitbook-description-html":"Data returned by the API service
\n"}},"type":"object","required":["data"],"title":"StackAIAPIDataResponse[SkillResponseV2]"},"StackAIAPIDataResponse_SkillVersionResponseV2_":{"properties":{"response_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Response Code","description":"Machine-readable response code, when provided.","x-gitbook-description-html":"Machine-readable response code, when provided.
\n"},"meta":{"additionalProperties":true,"type":"object","title":"Meta","description":"Additional metadata","default":{},"x-gitbook-description-html":"Additional metadata
\n"},"data":{"$ref":"#/components/schemas/SkillVersionResponseV2","description":"Data returned by the API service","x-gitbook-description-html":"Data returned by the API service
\n"}},"type":"object","required":["data"],"title":"StackAIAPIDataResponse[SkillVersionResponseV2]"},"StackAIAPIDataResponse_WebhookSubscriptionWithSecretResponseV2_":{"properties":{"response_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Response Code","description":"Machine-readable response code, when provided.","x-gitbook-description-html":"Machine-readable response code, when provided.
\n"},"meta":{"additionalProperties":true,"type":"object","title":"Meta","description":"Additional metadata","default":{},"x-gitbook-description-html":"Additional metadata
\n"},"data":{"$ref":"#/components/schemas/WebhookSubscriptionWithSecretResponseV2","description":"Data returned by the API service","x-gitbook-description-html":"Data returned by the API service
\n"}},"type":"object","required":["data"],"title":"StackAIAPIDataResponse[WebhookSubscriptionWithSecretResponseV2]"},"StackAIAPIDataResponse_list_EvalDatasetRowResponseV2__":{"properties":{"response_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Response Code","description":"Machine-readable response code, when provided.","x-gitbook-description-html":"Machine-readable response code, when provided.
\n"},"meta":{"additionalProperties":true,"type":"object","title":"Meta","description":"Additional metadata","default":{},"x-gitbook-description-html":"Additional metadata
\n"},"data":{"items":{"$ref":"#/components/schemas/EvalDatasetRowResponseV2"},"type":"array","title":"Data","description":"Data returned by the API service","x-gitbook-description-html":"Data returned by the API service
\n"}},"type":"object","required":["data"],"title":"StackAIAPIDataResponse[list[EvalDatasetRowResponseV2]]"},"StackAIAPIDataResponse_list_EvaluatorPreviewResponseV2__":{"properties":{"response_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Response Code","description":"Machine-readable response code, when provided.","x-gitbook-description-html":"Machine-readable response code, when provided.
\n"},"meta":{"additionalProperties":true,"type":"object","title":"Meta","description":"Additional metadata","default":{},"x-gitbook-description-html":"Additional metadata
\n"},"data":{"items":{"$ref":"#/components/schemas/EvaluatorPreviewResponseV2"},"type":"array","title":"Data","description":"Data returned by the API service","x-gitbook-description-html":"Data returned by the API service
\n"}},"type":"object","required":["data"],"title":"StackAIAPIDataResponse[list[EvaluatorPreviewResponseV2]]"},"StackAIAPIDataResponse_list_EvaluatorTemplateResponseV2__":{"properties":{"response_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Response Code","description":"Machine-readable response code, when provided.","x-gitbook-description-html":"Machine-readable response code, when provided.
\n"},"meta":{"additionalProperties":true,"type":"object","title":"Meta","description":"Additional metadata","default":{},"x-gitbook-description-html":"Additional metadata
\n"},"data":{"items":{"$ref":"#/components/schemas/EvaluatorTemplateResponseV2"},"type":"array","title":"Data","description":"Data returned by the API service","x-gitbook-description-html":"Data returned by the API service
\n"}},"type":"object","required":["data"],"title":"StackAIAPIDataResponse[list[EvaluatorTemplateResponseV2]]"},"StackAIAPIDataResponse_list_KnowledgeBaseQueryResultV2__":{"properties":{"response_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Response Code","description":"Machine-readable response code, when provided.","x-gitbook-description-html":"Machine-readable response code, when provided.
\n"},"meta":{"additionalProperties":true,"type":"object","title":"Meta","description":"Additional metadata","default":{},"x-gitbook-description-html":"Additional metadata
\n"},"data":{"items":{"$ref":"#/components/schemas/KnowledgeBaseQueryResultV2"},"type":"array","title":"Data","description":"Data returned by the API service","x-gitbook-description-html":"Data returned by the API service
\n"}},"type":"object","required":["data"],"title":"StackAIAPIDataResponse[list[KnowledgeBaseQueryResultV2]]"},"StackAIAPIError":{"properties":{"message":{"type":"string","title":"Message","description":"Message describing the error","x-gitbook-description-html":"Message describing the error
\n"}},"type":"object","required":["message"],"title":"StackAIAPIError","description":"Error detail model.","x-gitbook-description-html":"Error detail model.
\n"},"StackAIAPIErrorResponse":{"properties":{"response_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Response Code","description":"Machine-readable response code, when provided.","x-gitbook-description-html":"Machine-readable response code, when provided.
\n"},"meta":{"additionalProperties":true,"type":"object","title":"Meta","description":"Additional metadata","default":{},"x-gitbook-description-html":"Additional metadata
\n"},"errors":{"items":{"$ref":"#/components/schemas/StackAIAPIError"},"type":"array","title":"Errors","description":"List of errors","x-gitbook-description-html":"List of errors
\n"},"detail":{"items":{"type":"string"},"type":"array","title":"Detail","description":"Human-readable error messages. Use the HTTP status and error metadata to decide how to handle the failure.","readOnly":true,"x-gitbook-description-html":"Human-readable error messages. Use the HTTP status and error metadata to decide how to handle the failure.
\n"}},"type":"object","required":["detail"],"title":"StackAIAPIErrorResponse","description":"Error response model with status code and error list.","x-gitbook-description-html":"Error response model with status code and error list.
\n"},"StackAIAPIResponse":{"properties":{"response_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Response Code","description":"Machine-readable response code, when provided.","x-gitbook-description-html":"Machine-readable response code, when provided.
\n"},"meta":{"additionalProperties":true,"type":"object","title":"Meta","description":"Additional metadata","default":{},"x-gitbook-description-html":"Additional metadata
\n"}},"type":"object","title":"StackAIAPIResponse","description":"Base response model for StackAI API endpoints.\n\nProvides Pydantic validation and serialization with a helper method\nto convert to FastAPI's JSONResponse when needed.\n\nSerialization contract: `status_code` never reaches the body (it only feeds\n`to_json_response`), and `response_code`/`meta` are omitted when unset so\nsuccess bodies carry no filler. Error handlers that set them keep them.","x-gitbook-description-html":"Base response model for StackAI API endpoints.
\nProvides Pydantic validation and serialization with a helper method\nto convert to FastAPI's JSONResponse when needed.
\nSerialization contract: status_code never reaches the body (it only feeds\nto_json_response), and response_code/meta are omitted when unset so\nsuccess bodies carry no filler. Error handlers that set them keep them.
Processing status of a file in a knowledge base.
\n"},"StringListOption":{"properties":{"id":{"type":"string","title":"Id"},"label":{"type":"string","title":"Label"},"description":{"type":"string","maxLength":1024,"title":"Description","default":""},"color":{"$ref":"#/components/schemas/StringListOptionColor","default":"gray"},"order":{"type":"integer","maximum":10000000,"minimum":0,"title":"Order","default":0}},"type":"object","required":["label"],"title":"StringListOption"},"StringListOptionColor":{"type":"string","enum":["red","green","blue","yellow","purple","gray"],"title":"StringListOptionColor","description":"Store the different colors that can be used for the string list options.","x-gitbook-description-html":"Store the different colors that can be used for the string list options.
\n"},"StringListProperty":{"properties":{"type":{"type":"string","const":"string_list","title":"Type","default":"string_list"},"description":{"type":"string","maxLength":1024,"title":"Description","default":""},"order":{"type":"integer","minimum":0,"title":"Order","description":"Display order of this property within the schema.","default":0,"x-gitbook-description-html":"Display order of this property within the schema.
\n"},"options":{"items":{"$ref":"#/components/schemas/StringListOption"},"type":"array","title":"Options"}},"type":"object","title":"StringListProperty","description":"A property that contains a list of strings. Can be used to store tags as well.","x-gitbook-description-html":"A property that contains a list of strings. Can be used to store tags as well.
\n"},"StringProperty":{"properties":{"type":{"type":"string","const":"string","title":"Type","default":"string"},"description":{"type":"string","maxLength":1024,"title":"Description","default":""},"order":{"type":"integer","minimum":0,"title":"Order","description":"Display order of this property within the schema.","default":0,"x-gitbook-description-html":"Display order of this property within the schema.
\n"},"subtype":{"$ref":"#/components/schemas/StringSubtypeEnum","default":"plain"}},"type":"object","title":"StringProperty"},"StringSubtypeEnum":{"type":"string","enum":["plain","email","url","phone","file_path"],"title":"StringSubtypeEnum"},"TriggerTypeV2":{"type":"string","enum":["polling","webhook","scheduled"],"title":"TriggerTypeV2","description":"The trigger types exposed by the public Providers catalog.","x-gitbook-description-html":"The trigger types exposed by the public Providers catalog.
\n"},"UpdateKnowledgeBaseRequest":{"properties":{"connection_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Connection Id"},"connection_source_ids":{"items":{"type":"string"},"type":"array","uniqueItems":true,"title":"Connection Source Ids"},"website_sources":{"items":{"$ref":"#/components/schemas/SelectedWebsiteSource"},"type":"array","title":"Website Sources"},"source_file_authorization_enabled":{"type":"boolean","title":"Source File Authorization Enabled","default":false},"name":{"type":"string","maxLength":2048,"minLength":1,"title":"Name","default":"Unnamed Knowledge Base"},"description":{"type":"string","maxLength":2048,"title":"Description","default":""},"indexing_params":{"anyOf":[{"$ref":"#/components/schemas/KnowledgeBaseIndexingParamsRequest"},{"type":"null"}]},"org_level_role":{"anyOf":[{"$ref":"#/components/schemas/KnowledgeBaseRole"},{"type":"null"}]}},"additionalProperties":false,"type":"object","title":"UpdateKnowledgeBaseRequest","description":"Updates to apply to an existing knowledge base.","x-gitbook-description-html":"Updates to apply to an existing knowledge base.
\n"},"UpdateKnowledgeBaseRequestV2":{"properties":{"connection_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Connection Id"},"connection_source_ids":{"items":{"type":"string"},"type":"array","uniqueItems":true,"title":"Connection Source Ids"},"website_sources":{"items":{"$ref":"#/components/schemas/SelectedWebsiteSource"},"type":"array","title":"Website Sources"},"source_file_authorization_enabled":{"type":"boolean","title":"Source File Authorization Enabled","default":false},"name":{"type":"string","maxLength":2048,"minLength":1,"title":"Name","default":"Unnamed Knowledge Base"},"description":{"type":"string","maxLength":2048,"title":"Description","default":""},"indexing_params":{"anyOf":[{"$ref":"#/components/schemas/KnowledgeBaseIndexingParamsRequest"},{"type":"null"}]},"org_level_role":{"anyOf":[{"$ref":"#/components/schemas/KnowledgeBaseRole"},{"type":"null"}]}},"additionalProperties":false,"type":"object","title":"UpdateKnowledgeBaseRequest","description":"Updates to apply to an existing knowledge base.","x-gitbook-description-html":"Updates to apply to an existing knowledge base.
\n"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"WebhookEventType":{"type":"string","enum":["run.started","run.step.succeeded","run.step.failed","run.succeeded","run.failed","run.cancelled"],"title":"WebhookEventType","description":"Event types a subscription may register for; producers emit these (runs producer lands separately).","x-gitbook-description-html":"Event types a subscription may register for; producers emit these (runs producer lands separately).
\n"},"WebhookSubscriptionResponseV2":{"properties":{"subscription_id":{"type":"string","title":"Subscription Id"},"url":{"type":"string","title":"Url"},"event_types":{"items":{"$ref":"#/components/schemas/WebhookEventType"},"type":"array","title":"Event Types"},"created_at":{"type":"string","format":"date-time","title":"Created At"}},"type":"object","required":["subscription_id","url","event_types","created_at"],"title":"WebhookSubscriptionResponse","description":"A webhook subscription on the public v2 surface.\n\nNo `status` field: the surface only ever returns active subscriptions, so the value\ncould never vary.","x-gitbook-description-html":"A webhook subscription on the public v2 surface.
\nNo status field: the surface only ever returns active subscriptions, so the value\ncould never vary.
The signing secret for verifying deliveries. Shown only in this response and never retrievable afterwards; store it now, or delete the subscription and create a new one to get another secret.
\n"}},"type":"object","required":["subscription_id","url","event_types","created_at","secret"],"title":"WebhookSubscriptionWithSecretResponse","description":"A freshly created subscription, carrying its one-time signing secret.","x-gitbook-description-html":"A freshly created subscription, carrying its one-time signing secret.
\n"},"WorkflowState":{"type":"string","enum":["PENDING","RUNNING","PAUSED","RESUMED","COMPLETED","FAILED","CANCELLED"],"title":"WorkflowState","description":"Enum representing the possible states of a workflow.","x-gitbook-description-html":"Enum representing the possible states of a workflow.
\n"}},"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer","description":"Personal API key (sk_...) or supported user access JWT. See Authentication and authorization for endpoint restrictions and scopes. Use exactly one Authorization header.","x-gitbook-description-html":"Personal API key (sk_...) or supported user access JWT. See Authentication and authorization for endpoint restrictions and scopes. Use exactly one Authorization header.
\n"},"LegacyAPIKeyBearer":{"type":"http","scheme":"bearer","description":"Personal API key or the endpoint-specific legacy organization API key. Legacy inference uses the public organization key; legacy analytics uses the private organization key. This is not a password-grant login flow.","x-gitbook-description-html":"Personal API key or the endpoint-specific legacy organization API key. Legacy inference uses the public organization key; legacy analytics uses the private organization key. This is not a password-grant login flow.
\n"}}},"tags":[{"name":"v2","x-page-title":"REST API v2"},{"name":"v1","x-page-title":"Knowledge Bases v1"},{"name":"legacy","x-page-title":"Legacy inference and analytics"},{"name":"legacy-inference","x-page-title":"Inference v0","x-parent":"legacy","description":"Use the guides for end-to-end patterns, then the operations below for exact request and response contracts.","x-gitbook-description-html":"Use the guides for end-to-end patterns, then the operations below for exact request and response contracts.
\n"},{"name":"endpoint-getRun","x-page-title":"GET /inference/v0/runs/{org_id}/{run_id}","x-parent":"legacy-inference"},{"name":"endpoint-resumeRun","x-page-title":"POST /inference/v0/runs/{org_id}/{run_id}/resume","x-parent":"legacy-inference"},{"name":"endpoint-runDeployedFlow","x-page-title":"POST /inference/v0/run/{org_id}/{flow_id}","x-parent":"legacy-inference"},{"name":"knowledge-bases-v1","x-page-title":"Lifecycle, resources and sync","x-parent":"v1","description":"Use the guides for end-to-end patterns, then the operations below for exact request and response contracts.","x-gitbook-description-html":"Use the guides for end-to-end patterns, then the operations below for exact request and response contracts.
\n"},{"name":"endpoint-listKnowledgeBaseResources","x-page-title":"GET /v1/knowledge-bases/{knowledge_base_id}/resources","x-parent":"knowledge-bases-v1"},{"name":"endpoint-uploadKnowledgeBaseResource","x-page-title":"POST /v1/knowledge-bases/{knowledge_base_id}/resources","x-parent":"knowledge-bases-v1"},{"name":"endpoint-getKnowledgeBaseResource","x-page-title":"GET /v1/knowledge-bases/{knowledge_base_id}/resources/{resource_id}","x-parent":"knowledge-bases-v1"},{"name":"endpoint-deleteKnowledgeBaseResource","x-page-title":"DELETE /v1/knowledge-bases/{knowledge_base_id}/resources/{resource_id}","x-parent":"knowledge-bases-v1"},{"name":"endpoint-syncKnowledgeBase","x-page-title":"POST /v1/knowledge-bases/{knowledge_base_id}/sync","x-parent":"knowledge-bases-v1"},{"name":"endpoint-listKnowledgeBases","x-page-title":"GET /v1/knowledge-bases","x-parent":"knowledge-bases-v1"},{"name":"endpoint-createKnowledgeBase","x-page-title":"POST /v1/knowledge-bases","x-parent":"knowledge-bases-v1"},{"name":"endpoint-getKnowledgeBase","x-page-title":"GET /v1/knowledge-bases/{knowledge_base_id}","x-parent":"knowledge-bases-v1"},{"name":"endpoint-updateKnowledgeBase","x-page-title":"PATCH /v1/knowledge-bases/{knowledge_base_id}","x-parent":"knowledge-bases-v1"},{"name":"endpoint-deleteKnowledgeBase","x-page-title":"DELETE /v1/knowledge-bases/{knowledge_base_id}","x-parent":"knowledge-bases-v1"},{"name":"knowledge-bases","x-page-title":"Knowledge bases","x-parent":"v2","description":"Use the guides for end-to-end patterns, then the operations below for exact request and response contracts.","x-gitbook-description-html":"Use the guides for end-to-end patterns, then the operations below for exact request and response contracts.
\n"},{"name":"endpoint-listKnowledgeBasesV2","x-page-title":"GET /v2/knowledge-bases","x-parent":"knowledge-bases"},{"name":"endpoint-createKnowledgeBaseV2","x-page-title":"POST /v2/knowledge-bases","x-parent":"knowledge-bases"},{"name":"endpoint-getKnowledgeBaseV2","x-page-title":"GET /v2/knowledge-bases/{knowledge_base_id}","x-parent":"knowledge-bases"},{"name":"endpoint-updateKnowledgeBaseV2","x-page-title":"PATCH /v2/knowledge-bases/{knowledge_base_id}","x-parent":"knowledge-bases"},{"name":"endpoint-deleteKnowledgeBaseV2","x-page-title":"DELETE /v2/knowledge-bases/{knowledge_base_id}","x-parent":"knowledge-bases"},{"name":"endpoint-getKnowledgeBaseMetadataSchemasV2","x-page-title":"GET /v2/knowledge-bases/{knowledge_base_id}/metadata-schemas","x-parent":"knowledge-bases"},{"name":"endpoint-listKnowledgeBaseResourcesV2","x-page-title":"GET /v2/knowledge-bases/{knowledge_base_id}/resources","x-parent":"knowledge-bases"},{"name":"endpoint-uploadKnowledgeBaseResourceV2","x-page-title":"POST /v2/knowledge-bases/{knowledge_base_id}/resources","x-parent":"knowledge-bases"},{"name":"endpoint-getKnowledgeBaseResourceV2","x-page-title":"GET /v2/knowledge-bases/{knowledge_base_id}/resources/{resource_id}","x-parent":"knowledge-bases"},{"name":"endpoint-deleteKnowledgeBaseResourceV2","x-page-title":"DELETE /v2/knowledge-bases/{knowledge_base_id}/resources/{resource_id}","x-parent":"knowledge-bases"},{"name":"endpoint-getKnowledgeBaseResourceDownloadUrlV2","x-page-title":"GET /v2/knowledge-bases/{knowledge_base_id}/resources/{resource_id}/download","x-parent":"knowledge-bases"},{"name":"endpoint-queryKnowledgeBaseV2","x-page-title":"POST /v2/knowledge-bases/{knowledge_base_id}/query","x-parent":"knowledge-bases"},{"name":"endpoint-syncKnowledgeBaseV2","x-page-title":"POST /v2/knowledge-bases/{knowledge_base_id}/sync","x-parent":"knowledge-bases"},{"name":"projects","x-page-title":"Project IO schemas","x-parent":"v2","description":"Use the guides for end-to-end patterns, then the operations below for exact request and response contracts.","x-gitbook-description-html":"Use the guides for end-to-end patterns, then the operations below for exact request and response contracts.
\n"},{"name":"endpoint-getProjectIoSchemaV2","x-page-title":"GET /v2/projects/{project_id}/io-schema","x-parent":"projects"},{"name":"eval-datasets","x-page-title":"Evaluation datasets","x-parent":"v2","description":"Use the guides for end-to-end patterns, then the operations below for exact request and response contracts.","x-gitbook-description-html":"Use the guides for end-to-end patterns, then the operations below for exact request and response contracts.
\n"},{"name":"endpoint-listEvalDatasetsV2","x-page-title":"GET /v2/evals/datasets","x-parent":"eval-datasets"},{"name":"endpoint-createEvalDatasetV2","x-page-title":"POST /v2/evals/datasets","x-parent":"eval-datasets"},{"name":"endpoint-getEvalDatasetV2","x-page-title":"GET /v2/evals/datasets/{dataset_id}","x-parent":"eval-datasets"},{"name":"endpoint-updateEvalDatasetV2","x-page-title":"PATCH /v2/evals/datasets/{dataset_id}","x-parent":"eval-datasets"},{"name":"endpoint-deleteEvalDatasetV2","x-page-title":"DELETE /v2/evals/datasets/{dataset_id}","x-parent":"eval-datasets"},{"name":"endpoint-addEvalDatasetRowsV2","x-page-title":"POST /v2/evals/datasets/{dataset_id}/rows","x-parent":"eval-datasets"},{"name":"endpoint-listEvalDatasetRowsV2","x-page-title":"GET /v2/evals/datasets/{dataset_id}/rows","x-parent":"eval-datasets"},{"name":"endpoint-importEvalDatasetRowsV2","x-page-title":"POST /v2/evals/datasets/{dataset_id}/imports","x-parent":"eval-datasets"},{"name":"endpoint-getEvalDatasetRowV2","x-page-title":"GET /v2/evals/datasets/{dataset_id}/rows/{row_id}","x-parent":"eval-datasets"},{"name":"endpoint-updateEvalDatasetRowV2","x-page-title":"PATCH /v2/evals/datasets/{dataset_id}/rows/{row_id}","x-parent":"eval-datasets"},{"name":"endpoint-deleteEvalDatasetRowV2","x-page-title":"DELETE /v2/evals/datasets/{dataset_id}/rows/{row_id}","x-parent":"eval-datasets"},{"name":"eval-evaluators","x-page-title":"Evaluators and previews","x-parent":"v2","description":"Use the guides for end-to-end patterns, then the operations below for exact request and response contracts.","x-gitbook-description-html":"Use the guides for end-to-end patterns, then the operations below for exact request and response contracts.
\n"},{"name":"endpoint-listEvaluatorsV2","x-page-title":"GET /v2/evals/evaluators","x-parent":"eval-evaluators"},{"name":"endpoint-createEvaluatorV2","x-page-title":"POST /v2/evals/evaluators","x-parent":"eval-evaluators"},{"name":"endpoint-getEvaluatorV2","x-page-title":"GET /v2/evals/evaluators/{evaluator_id}","x-parent":"eval-evaluators"},{"name":"endpoint-updateEvaluatorV2","x-page-title":"PATCH /v2/evals/evaluators/{evaluator_id}","x-parent":"eval-evaluators"},{"name":"endpoint-deleteEvaluatorV2","x-page-title":"DELETE /v2/evals/evaluators/{evaluator_id}","x-parent":"eval-evaluators"},{"name":"endpoint-previewEvaluatorV2","x-page-title":"POST /v2/evals/evaluator-previews","x-parent":"eval-evaluators"},{"name":"endpoint-listEvaluatorTemplatesV2","x-page-title":"GET /v2/evals/evaluator-templates","x-parent":"eval-evaluators"},{"name":"eval-experiments","x-page-title":"Experiments and jobs","x-parent":"v2","description":"Use the guides for end-to-end patterns, then the operations below for exact request and response contracts.","x-gitbook-description-html":"Use the guides for end-to-end patterns, then the operations below for exact request and response contracts.
\n"},{"name":"endpoint-listEvalExperimentsV2","x-page-title":"GET /v2/evals/experiments","x-parent":"eval-experiments"},{"name":"endpoint-createEvalExperimentV2","x-page-title":"POST /v2/evals/experiments","x-parent":"eval-experiments"},{"name":"endpoint-getEvalExperimentV2","x-page-title":"GET /v2/evals/experiments/{experiment_id}","x-parent":"eval-experiments"},{"name":"endpoint-updateEvalExperimentV2","x-page-title":"PATCH /v2/evals/experiments/{experiment_id}","x-parent":"eval-experiments"},{"name":"endpoint-deleteEvalExperimentV2","x-page-title":"DELETE /v2/evals/experiments/{experiment_id}","x-parent":"eval-experiments"},{"name":"endpoint-listEvalExperimentRowsV2","x-page-title":"GET /v2/evals/experiments/{experiment_id}/rows","x-parent":"eval-experiments"},{"name":"endpoint-getEvalExperimentStatusV2","x-page-title":"GET /v2/evals/experiments/{experiment_id}/status","x-parent":"eval-experiments"},{"name":"endpoint-createEvalExperimentJobV2","x-page-title":"POST /v2/evals/experiments/{experiment_id}/jobs","x-parent":"eval-experiments"},{"name":"endpoint-getEvalExperimentJobV2","x-page-title":"GET /v2/evals/experiments/{experiment_id}/jobs/{job_id}","x-parent":"eval-experiments"},{"name":"eval-monitors","x-page-title":"Production monitors","x-parent":"v2","description":"Use the guides for end-to-end patterns, then the operations below for exact request and response contracts.","x-gitbook-description-html":"Use the guides for end-to-end patterns, then the operations below for exact request and response contracts.
\n"},{"name":"endpoint-getEvalMonitorLimitsV2","x-page-title":"GET /v2/evals/monitor-limits","x-parent":"eval-monitors"},{"name":"endpoint-listEvalMonitorsV2","x-page-title":"GET /v2/evals/monitors","x-parent":"eval-monitors"},{"name":"endpoint-createEvalMonitorV2","x-page-title":"POST /v2/evals/monitors","x-parent":"eval-monitors"},{"name":"endpoint-getEvalMonitorV2","x-page-title":"GET /v2/evals/monitors/{monitor_id}","x-parent":"eval-monitors"},{"name":"endpoint-updateEvalMonitorV2","x-page-title":"PATCH /v2/evals/monitors/{monitor_id}","x-parent":"eval-monitors"},{"name":"endpoint-deleteEvalMonitorV2","x-page-title":"DELETE /v2/evals/monitors/{monitor_id}","x-parent":"eval-monitors"},{"name":"endpoint-getEvalMonitorScoreStatsV2","x-page-title":"GET /v2/evals/monitors/{monitor_id}/score-stats","x-parent":"eval-monitors"},{"name":"endpoint-getEvalMonitorAlertV2","x-page-title":"GET /v2/evals/monitors/{monitor_id}/alert","x-parent":"eval-monitors"},{"name":"endpoint-updateEvalMonitorAlertV2","x-page-title":"PATCH /v2/evals/monitors/{monitor_id}/alert","x-parent":"eval-monitors"},{"name":"endpoint-listEvalMonitorSampledRunsV2","x-page-title":"GET /v2/evals/monitors/{monitor_id}/sampled-runs","x-parent":"eval-monitors"},{"name":"eval-scores","x-page-title":"Run scores","x-parent":"v2","description":"Use the guides for end-to-end patterns, then the operations below for exact request and response contracts.","x-gitbook-description-html":"Use the guides for end-to-end patterns, then the operations below for exact request and response contracts.
\n"},{"name":"endpoint-createEvalRunScoreV2","x-page-title":"POST /v2/evals/runs/{run_id}/scores","x-parent":"eval-scores"},{"name":"endpoint-listEvalRunScoresV2","x-page-title":"GET /v2/evals/runs/{run_id}/scores","x-parent":"eval-scores"},{"name":"endpoint-getEvalRunScoreV2","x-page-title":"GET /v2/evals/scores/{score_id}","x-parent":"eval-scores"},{"name":"legacy-analytics","x-page-title":"Analytics","x-parent":"legacy","description":"Use the guides for end-to-end patterns, then the operations below for exact request and response contracts.","x-gitbook-description-html":"Use the guides for end-to-end patterns, then the operations below for exact request and response contracts.
\n"},{"name":"endpoint-getAnalyticsDataApi","x-page-title":"GET /analytics/org/{org_id}/flows/{flow_id}","x-parent":"legacy-analytics"},{"name":"providers","x-page-title":"Providers and actions","x-parent":"v2","description":"Use the guides for end-to-end patterns, then the operations below for exact request and response contracts.","x-gitbook-description-html":"Use the guides for end-to-end patterns, then the operations below for exact request and response contracts.
\n"},{"name":"endpoint-listProvidersV2","x-page-title":"GET /v2/providers","x-parent":"providers"},{"name":"endpoint-getProviderV2","x-page-title":"GET /v2/providers/{provider_id}","x-parent":"providers"},{"name":"endpoint-listProviderActionsV2","x-page-title":"GET /v2/providers/{provider_id}/actions","x-parent":"providers"},{"name":"endpoint-getProviderActionV2","x-page-title":"GET /v2/providers/{provider_id}/actions/{action_id}","x-parent":"providers"},{"name":"endpoint-listProviderTriggersV2","x-page-title":"GET /v2/providers/{provider_id}/triggers","x-parent":"providers"},{"name":"endpoint-getProviderTriggerV2","x-page-title":"GET /v2/providers/{provider_id}/triggers/{trigger_id}","x-parent":"providers"},{"name":"endpoint-runProviderActionV2","x-page-title":"POST /v2/providers/{provider_id}/actions/{action_id}/run","x-parent":"providers"},{"name":"connections","x-page-title":"Connections","x-parent":"v2","description":"Use the guides for end-to-end patterns, then the operations below for exact request and response contracts.","x-gitbook-description-html":"Use the guides for end-to-end patterns, then the operations below for exact request and response contracts.
\n"},{"name":"endpoint-listConnectionsV2","x-page-title":"GET /v2/connections","x-parent":"connections"},{"name":"webhooks","x-page-title":"Webhook subscriptions","x-parent":"v2","description":"Use the guides for end-to-end patterns, then the operations below for exact request and response contracts.","x-gitbook-description-html":"Use the guides for end-to-end patterns, then the operations below for exact request and response contracts.
\n"},{"name":"endpoint-createWebhookSubscriptionV2","x-page-title":"POST /v2/webhooks/subscriptions","x-parent":"webhooks"},{"name":"endpoint-listWebhookSubscriptionsV2","x-page-title":"GET /v2/webhooks/subscriptions","x-parent":"webhooks"},{"name":"endpoint-deleteWebhookSubscriptionV2","x-page-title":"DELETE /v2/webhooks/subscriptions/{subscription_id}","x-parent":"webhooks"},{"name":"runs","x-page-title":"Runs","x-parent":"v2","description":"Use the guides for end-to-end patterns, then the operations below for exact request and response contracts.","x-gitbook-description-html":"Use the guides for end-to-end patterns, then the operations below for exact request and response contracts.
\n"},{"name":"endpoint-startRunV2","x-page-title":"POST /v2/runs","x-parent":"runs"},{"name":"endpoint-listRunsV2","x-page-title":"GET /v2/runs","x-parent":"runs"},{"name":"endpoint-getRunV2","x-page-title":"GET /v2/runs/{run_id}","x-parent":"runs"},{"name":"endpoint-cancelRunV2","x-page-title":"POST /v2/runs/{run_id}/cancel","x-parent":"runs"},{"name":"endpoint-resumeRunV2","x-page-title":"POST /v2/runs/{run_id}/resume","x-parent":"runs"},{"name":"skills","x-page-title":"Skills and versions","x-parent":"v2","description":"Use the guides for end-to-end patterns, then the operations below for exact request and response contracts.","x-gitbook-description-html":"Use the guides for end-to-end patterns, then the operations below for exact request and response contracts.
\n"},{"name":"endpoint-listSkillsV2","x-page-title":"GET /v2/skills","x-parent":"skills"},{"name":"endpoint-createSkillV2","x-page-title":"POST /v2/skills","x-parent":"skills"},{"name":"endpoint-getSkillV2","x-page-title":"GET /v2/skills/{skill_id}","x-parent":"skills"},{"name":"endpoint-deleteSkillV2","x-page-title":"DELETE /v2/skills/{skill_id}","x-parent":"skills"},{"name":"endpoint-listSkillVersionsV2","x-page-title":"GET /v2/skills/{skill_id}/versions","x-parent":"skills"},{"name":"endpoint-createSkillVersionV2","x-page-title":"POST /v2/skills/{skill_id}/versions","x-parent":"skills"},{"name":"endpoint-getSkillVersionV2","x-page-title":"GET /v2/skills/{skill_id}/versions/{version}","x-parent":"skills"}],"servers":[{"url":"https://api.stack-ai.com","description":"Hosted API. Use your deployment-specific origin for private installations.","x-gitbook-description-html":"Hosted API. Use your deployment-specific origin for private installations.
\n"}]}