raia API — Developer Guide

Find an agent knowledge file

Use Agent-Secret-Key to locate a file belonging to your agent. Start at zero-based page=0; pageSize accepts 1–100 files. The example sorts newest first using orderBy=createdAt and orderDirection=DESC. Read data, currentPage and hasNextPage; increment the page and continue only while hasNextPage is true.

curl --request GET "https://api.raia2.com/external/agent-files/by-api-key/paginated?page=0&pageSize=10&orderBy=createdAt&orderDirection=DESC" \
  --header "Agent-Secret-Key: $RAIA_AGENT_SECRET_KEY"

Set RAIA_FILE_ID to a returned data[].id, not vectorStoreFileId, then read that file. The response is metadata and upload status, not raw file text. Inspect vectorStoreUploadStatus: processing means upload in progress, done means upload complete, failed signals failure, and null means not uploaded. To check retrieval quality, ask a known-answer question and compare the answer with your source; file metadata alone does not prove an answer.

curl --request GET "https://api.raia2.com/external/agent-files/${RAIA_FILE_ID}" \
  --header "Agent-Secret-Key: $RAIA_AGENT_SECRET_KEY"

Inspect a prompt execution

An execution is a recorded run of an agent request. Use Organization-Secret-Key to investigate a failed request; this example lists failed prompt executions, newest first. Filter source with conversation, prompt or mcp, and status with RUNNING, COMPLETED or FAILED. The reference also lists agent, request-ID and date filters; rootOnly defaults to true. Omit page and pageSize in your first request: their numbering, defaults and bounds are not specified for execution history.

curl --request GET "https://api.raia2.com/external/agent-prompt-executions?source=prompt&status=FAILED&orderBy=startedAt&orderDirection=DESC" \
  --header "Organization-Secret-Key: $RAIA_ORGANIZATION_SECRET_KEY"

Read data for the execution records and the page metadata for the returned result set. Set RAIA_EXECUTION_ID to a returned data[].id, then read that record. Check status and response; for a failure, inspect errorCode and errorMessage. Use traceId and parentExecutionId to relate records. These requests read history without starting or retrying a run. Check the destination separately when you need to confirm an external action succeeded.

curl --request GET "https://api.raia2.com/external/agent-prompt-executions/${RAIA_EXECUTION_ID}" \
  --header "Organization-Secret-Key: $RAIA_ORGANIZATION_SECRET_KEY"

Review your organization’s default model

Use Organization-Secret-Key and status=active to see your organization's active model access records. Each record connects a model to your organization and has its own id. The response is an array with id, modelId, modelName, status, isDefault, createdAt and updatedAt. Without status, the list includes active and archived access records whose global model is active. Before changing the default, save the current default record's id so you can switch back. Set RAIA_MODEL_ACCESS_ID to your chosen active record's id, not modelId or modelName.

curl --request GET "https://api.raia2.com/external/organizations/llm-models?status=active" \
  --header "Organization-Secret-Key: $RAIA_ORGANIZATION_SECRET_KEY"

curl --request PUT "https://api.raia2.com/external/organizations/llm-models/${RAIA_MODEL_ACCESS_ID}/default" \
  --header "Organization-Secret-Key: $RAIA_ORGANIZATION_SECRET_KEY"

HTTP 200 returns the selected access record. Check that isDefault is true, then reread the list with the preceding GET request. For HTTP 400, check that the selected record is active. For 404, check the access-record ID and organization key. To switch back, repeat the PUT request with the saved prior access-record ID if it is still active. The specification does not describe how existing agents inherit this setting.

Users8 endpoints

Conversations15 endpoints

Prompts4 endpoints

Agents12 endpoints

Agent-files9 endpoints

Conversation Message Feedbacks1 endpoints

Resource Usage Logs1 endpoints

Organization API Key47 endpoints