Skip to content
OperadeDocs

Search documentation

Type to search documentation.

DashboardContact
Documentation
Copy page
Open raw Markdown

API quickstart

Create an agent with a workspace API key, then read the created agent back through the public API.

Prerequisites and API key safety#

You need an Operade workspace and an owner or admin dashboard session. In the dashboard, open Settings, select API keys, and create a key. The complete API key is shown once. Copy it before closing the dialog; Operade cannot display it again.

Use placeholders in scripts and secret storage in your own environment. Never commit a real key. The examples below use YOUR_API_KEY, YOUR_WORKSPACE_ID, and YOUR_AGENT_ID deliberately.

Your workspace ID is embedded in the key without exposing the secret part. If the key begins cxk_IDENTIFIER_..., use ws_IDENTIFIER as YOUR_WORKSPACE_ID. Keep the complete key private.

Create and read an agent#

The live operation reference for the POST request is createAgent.

bash
curl --request POST 'https://operade.ai/api/v1/workspaces/YOUR_WORKSPACE_ID/agents' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"name":"Example support agent"}'

Copy the id from the response. Use it as YOUR_AGENT_ID in the GET request. The live operation reference is getAgent.

bash
curl --request GET 'https://operade.ai/api/v1/workspaces/YOUR_WORKSPACE_ID/agents/YOUR_AGENT_ID' \
  --header 'Authorization: Bearer YOUR_API_KEY'

A successful read returns the agent, its active version information, and its configuration. The agent was created with a Main branch and an initial immutable version.

Verify, recover, and revoke#

  • A 401 response means authentication is missing, invalid, or revoked. Check that the full key was copied and that it is still active.
  • A 403 response means the caller cannot access the requested operation or workspace.
  • A 404 response usually means the workspace or agent ID does not match what the key can access.
  • A 422 response means a request field failed validation; compare the request with the linked operation reference.

Verification is complete when the GET response contains the same agent ID returned by POST. If the full key was lost, recovery means revoking that key in Settings > API keys and creating another; it cannot be recovered. Revoke any key that may have been exposed. Revocation takes effect on its next use.

Continue with core concepts before automating drafts or publishing.

On this page
  1. Prerequisites and API key safety
  2. Create and read an agent
  3. Verify, recover, and revoke