# API introduction

The Operade API exposes reviewed REST operations for building and operating text-based agents. The canonical production base URL is `https://operade.ai/api/v1`. Operation pages under API Reference are generated from the reviewed public OpenAPI contract and operation metadata.

## Request model

Paths are workspace-scoped where a resource belongs to a Workspace. Use the exact method and path shown on an operation page. Most request and response bodies are JSON; Procedure and Knowledge file imports use multipart form data. Successful deletion or logout operations may return HTTP 204 with no body.

Customer API operations that explicitly allow API keys accept `Authorization: Bearer YOUR_API_KEY`. Dashboard session operations use the secure `cx_session` cookie and have additional request-intent protection for mutations. Provider callbacks, such as Telegram, have their own verification header and are not customer calls.

## First request

Start by creating an API key in the dashboard, copy it when it is shown, and choose an operation whose page says API key allowed. Replace the path Workspace identifier with the Workspace bound to the key.

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

An invalid or revoked key receives HTTP 401. A valid key used for a different Workspace receives HTTP 404 so cross-Workspace existence is not disclosed.

## Read operation pages

Each operation page lists its class, required role, API-key support, parameters, request schema, response schemas, reviewed errors, and a canonical example. Those pages are the precise contract for a route. Foundation pages explain behavior shared across routes; they do not override operation-specific requirements.

## Limits and safety

There is no general `Idempotency-Key` contract. Use the documented concurrency fields for branch, reconciliation, revert, and deployment operations. Do not log credentials or copy private payloads into troubleshooting records. Operade currently documents text-agent functionality and does not imply voice, telephony, or an official SDK.

Continue with [Authentication](/docs/reference/api/authentication), [Headers and content types](/docs/reference/api/headers-and-content-types), and [API errors](/docs/reference/api/errors).