REST API

Knowledge, evaluations, and benchmarks API

Ingest and search knowledge, evaluate answers and workflows, and compare model benchmark results.

Use these endpoints to build a knowledge collection, retrieve grounded context, measure answer quality, run evaluation datasets, and compare models. The RAG and evaluation-run routes described here require an authenticated Agent Studio browser session; the dataset and benchmark handlers do not perform a session check in the current implementation.

ℹ️Examples use https://agent-studio.example.com as a placeholder. Replace it with your Agent Studio origin. For session-protected routes, send the session cookie issued by your configured authentication provider. API-key coverage is not implied.

Common responses

Successful requests return JSON. Most operations use success: true; RAG ingestion returns the created document, searches identify their mode, and evaluation or benchmark operations return a data object. A missing session returns 401. Validation failures return 400, and an unexpected execution failure returns 500 with an error string.

Knowledge ingestion

Ingest text

POST/api/rag/ingest

contentstringbodyrequired

Non-empty document text.

titlestringbody

Document title. Defaults to `Untitled Document`.

collectionstringbody

Collection namespace. Defaults to `default`.

sourcestringbody

Source identifier or URL.

mimeTypestringbody

Content type. Defaults to `text/plain`.

chunkingobjectbody

Chunking configuration.

metadataobjectbody

Metadata stored with the document.

tagsstring[]body

Tags added to the stored metadata.

embeddingModelstringbody

Embedding model override.

useParentChunkingbooleanbody

Enable parent-child chunking. Defaults to `false`.

Response

200Document ingested

400Content is missing or empty

422Ingestion produced no usable chunks

$_cURL

curl --request POST \
  --url https://agent-studio.example.com/api/rag/ingest \
  --header 'Content-Type: application/json' \
  --data '{
  "content": "<string>",
  "title": "<string>",
  "collection": "<string>",
  "source": "<string>",
  "mimeType": "<string>",
  "chunking": {},
  "metadata": {},
  "tags": [],
  "embeddingModel": "<string>",
  "useParentChunking": false
}'

{ "success": true, "document": { "documentId": "doc_example", "chunkCount": 4, "totalTokens": 830 } }

bash

curl -X POST 'https://agent-studio.example.com/api/rag/ingest' \
  -H 'Content-Type: application/json' \
  -H 'Cookie: __session=<session-cookie>' \
  -d '{"title":"Support policy","collection":"support","content":"Refund requests must include an order ID.","tags":["policy"]}'

Ingest a URL

POST/api/rag/fetch-url

urlstringbodyrequired

HTTP or HTTPS URL to fetch.

collectionstringbody

Target collection. Defaults to `default`.

tagsstring[]body

Tags stored with the document.

chunkingobjectbody

Chunking configuration.

useParentChunkingbooleanbody

Enable parent-child chunking. Defaults to `false`.

embeddingModelstringbody

Embedding model override.

Response

200Page fetched and ingested

400Invalid URL, oversized page, or insufficient text

402The remote server did not return a successful response

$_cURL

curl --request POST \
  --url https://agent-studio.example.com/api/rag/fetch-url \
  --header 'Content-Type: application/json' \
  --data '{
  "url": "https://example.com/policy",
  "collection": "support",
  "tags": [
    "policy"
  ],
  "chunking": {},
  "useParentChunking": false,
  "embeddingModel": "text-embedding-3-small"
}'

{ "success": true, "document": { "title": "Example policy", "url": "https://example.com/policy", "chunkCount": 6, "totalTokens": 1200, "documentId": "doc_example" } }

The fetch operation follows redirects, allows at most 15 seconds, rejects pages larger than 5 MB, and requires at least 50 characters of extracted content.

Retrieval and analysis

Search knowledge

POST/api/rag/search

querystringbodyrequired

Non-empty search query.

collectionstringbody

Collection to search.

limitnumberbody

Maximum results. Defaults to `5`.

minScorenumberbody

Minimum relevance score. Defaults to `0.2`.

metadataFilterobjectbody

Metadata constraints applied during retrieval.

generateAnswerbooleanbody

Return grounded question answering output. Defaults to `false`.

augmentPromptbooleanbody

Return a prompt containing retrieved context. Defaults to `false`.

basePromptstringbody

Prompt used by augmentation mode.

systemPromptstringbody

System instruction used by answer generation.

useHybridSearchbooleanbody

Combine vector and lexical search. Defaults to `false`.

expandToParentbooleanbody

Return parent context for matching child chunks. Defaults to `false`.

useRerankingbooleanbody

Rerank retrieved results. Defaults to `false`.

useHyDEbooleanbody

Use hypothetical-document retrieval. Defaults to `false`.

Response

200Search completed

400Query is missing or empty

$_cURL

curl --request POST \
  --url https://agent-studio.example.com/api/rag/search \
  --header 'Content-Type: application/json' \
  --data '{
  "query": "What does a refund request require?",
  "collection": "support",
  "limit": 5,
  "minScore": 0.2,
  "metadataFilter": "\"tags\":[\"policy\"]",
  "generateAnswer": false,
  "augmentPrompt": true,
  "basePrompt": "Answer using only the supplied context.",
  "systemPrompt": "Be concise and cite the retrieved policy.",
  "useHybridSearch": true,
  "expandToParent": false,
  "useReranking": true,
  "useHyDE": false
}'

{ "success": true, "mode": "search", "chunkCount": 1, "results": [ { "content": "Refund requests must include an order ID.", "score": 0.87 } ] }

Set only one of generateAnswer or augmentPrompt. Answer mode takes precedence when both are true; otherwise the endpoint returns raw search results. When no chunks pass the threshold, the response includes a warning to lower minScore or broaden the metadata filter.

Evaluate a grounded answer

POST/api/rag/evaluate

querystringbodyrequired

The original question.

contextChunksarraybody

Context supplied to the answer. Defaults to an empty array.

generatedAnswerstringbodyrequired

The answer to evaluate.

Response

200Evaluation completed

400Required input is missing

$_cURL

curl --request POST \
  --url https://agent-studio.example.com/api/rag/evaluate \
  --header 'Content-Type: application/json' \
  --data '{
  "query": "What does a refund request require?",
  "contextChunks": [
    "Refund requests must include an order ID."
  ],
  "generatedAnswer": "A refund request must include an order ID."
}'

{ "success": true, "evaluation": { "contextRelevance": 0.9, "groundedness": 0.86, "answerRelevance": 0.92 } }

List knowledge documents

GET/api/rag/documents

collectionstringquery

Filter by collection.

limitnumberquery

Maximum documents. Defaults to `50`.

offsetnumberquery

Number of documents to skip. Defaults to `0`.

includeCollectionsbooleanquery

Include collection names when exactly `true`.

Response

200Documents listed

$_cURL

curl --request GET \
  --url https://agent-studio.example.com/api/rag/documents?collection=support&limit=50&offset=0&includeCollections=true

{ "success": true, "documents": [], "total": 0, "stats": {}, "collections": ["support"] }

Delete a knowledge document

DELETE/api/rag/documents

idstringqueryrequired

Document ID owned by the current user.

Response

200Document deleted

404Document was not found for the current user

$_cURL

curl --request DELETE \
  --url https://agent-studio.example.com/api/rag/documents?id=doc_example

{ "success": true, "deletedId": "doc_example" }

Evaluation datasets and runs

List datasets

GET/api/evals/datasets

Response

200Datasets listed

$_cURL

curl --request GET \
  --url https://agent-studio.example.com/api/evals/datasets

{ "success": true, "data": [], "totalCount": 0 }

Create a dataset

POST/api/evals/datasets

namestringbodyrequired

Dataset name.

itemsarraybodyrequired

Evaluation cases.

descriptionstringbody

Defaults to `Custom Evaluation Dataset`.

categorystringbody

Defaults to `CUSTOM`.

targetTypestringbody

Defaults to `GRAPH`.

Response

200Dataset created

400Name or items array is missing

$_cURL

curl --request POST \
  --url https://agent-studio.example.com/api/evals/datasets \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Support answers",
  "items": [],
  "description": "Regression cases for support answers",
  "category": "CUSTOM",
  "targetType": "GRAPH"
}'

{ "success": true, "data": { "id": "dataset_example", "name": "Support answers", "items": [] } }

⚠️Custom evaluation datasets are held by the dataset store used by the running process. Do not assume they survive a restart unless your deployment adds durable storage.

Run an evaluation

POST/api/evals/run

datasetIdstringbodyrequired

Evaluation dataset ID.

targetTypestringbody

Defaults to `GRAPH`.

targetIdstringbody

Defaults to `default_target`.

targetNamestringbody

Defaults to `Agent Mission Control Graph`.

targetModelstringbody

Model used by the target.

judgeConfigobjectbody

Judge model, temperature, metrics, pass threshold, and optional custom instructions.

Response

200Evaluation completed

400Dataset ID is missing

$_cURL

curl --request POST \
  --url https://agent-studio.example.com/api/evals/run \
  --header 'Content-Type: application/json' \
  --data '{
  "datasetId": "dataset_example",
  "targetType": "GRAPH",
  "targetId": "default_target",
  "targetName": "Support workflow",
  "targetModel": "meta-llama/llama-3.3-70b-versatile",
  "judgeConfig": "\"temperature\":0,\"passThreshold\":0.75"
}'

{ "success": true, "data": { "id": "run_example", "status": "COMPLETED", "summary": { "overallScore": 84, "passRate": 80 } } }

The default judge uses temperature 0, pass threshold 0.75, and the FAITHFULNESS, ANSWER_RELEVANCE, SEMANTIC_CORRECTNESS, and SAFETY_POLICY metrics.

List evaluation runs

GET/api/evals/runs

Response

200Runs listed

$_cURL

curl --request GET \
  --url https://agent-studio.example.com/api/evals/runs

{ "success": true, "data": [], "totalCount": 0 }

Compare evaluation runs

GET/api/evals/compare

runAstringqueryrequired

First run ID.

runBstringqueryrequired

Second run ID.

Response

200Comparison returned

404One or both runs were not found for the current user

$_cURL

curl --request GET \
  --url https://agent-studio.example.com/api/evals/compare?runA=run_a&runB=run_b

{ "success": true, "data": { "runA": "run_a", "runB": "run_b" } }

Benchmarks

List benchmark suites

GET/api/benchmarks/suites

Response

200Suites listed

$_cURL

curl --request GET \
  --url https://agent-studio.example.com/api/benchmarks/suites

{ "success": true, "data": { "suites": [], "totalSuites": 0, "totalTestCases": 0 } }

Run a benchmark

POST/api/benchmarks/run

suiteIdstringbody

Suite ID. An unknown or absent ID selects the first built-in suite.

modelstringbody

Model ID. Defaults to the suite recommendation, then the configured fallback.

skillNamestringbody

Scorecard label. Defaults to `Active Agent Architecture`.

Response

200Benchmark completed

$_cURL

curl --request POST \
  --url https://agent-studio.example.com/api/benchmarks/run \
  --header 'Content-Type: application/json' \
  --data '{
  "suiteId": "suite_example",
  "model": "meta-llama/llama-3.3-70b-versatile",
  "skillName": "Support triage"
}'

{ "success": true, "data": { "skillName": "Support triage", "overallScore": 87 } }

Compare benchmark models

POST/api/benchmarks/compare

suiteIdstringbody

Suite ID. An unknown or absent ID selects the first built-in suite.

modelsstring[]bodyrequired

One or more model IDs.

Response

200Model comparison completed

400Models are missing

$_cURL

curl --request POST \
  --url https://agent-studio.example.com/api/benchmarks/compare \
  --header 'Content-Type: application/json' \
  --data '{
  "suiteId": "suite_example",
  "models": [
    "meta-llama/llama-3.3-70b-versatile"
  ]
}'

{ "success": true, "data": [], "suiteId": "suite_example", "suiteName": "Example suite" }

Next steps

Ingest knowledge

Build a collection from text and files.

Run evaluations

Configure and interpret evaluation runs.

Benchmark models

Compare candidate models with a benchmark suite.