Product-owned identity
Each product issues and checks its own credentials. A key resolves to an account or workspace and a set of scopes; ownership decides what it can read.
Access layer / software
ApexAPI
Typed, scoped HTTP into every ApexAi product.
ApexAPI is how software uses ApexAi products. Each product publishes its own contract, identity, and deployment; ApexAPI is the discipline they share—typed requests, scoped credentials, explicit side effects, idempotent retries, stable errors, and bounded retrieval.
At a glance
- Who it is for
- Developers whose applications submit web-data jobs, send communications, answer support conversations, or read results and history.
- What it gives you
- Typed, scoped contracts per product, with idempotent sends, stable error codes, and bounded retrieval.
- How it is reached
- HTTPS with credentials each product issues. One contract per product; no shared gateway, base URL, or sign-on.
- Today
- ScrawlBuiltCommunicationsBuiltDevOpsPlannedNot self-serve yet; commercial access follows each product.
When to use it
Software that runs product work without a person watching.
Use ApexAPI when an application or service owns the call and its retries: submitting web-data jobs, sending customer notifications, reading results and history into your own systems.
Explicit side effects
Anything that spends credits or reaches a provider is a distinct, scoped operation—never a side effect of a read.
Lifecycle IDs
Work returns an ID immediately. Scrawl jobs are accepted and run asynchronously; communications return their record with its current status.
Bounded retrieval
Lists are paginated or bounded, reads are limited to what the caller owns, and artifacts are fetched per job and per file.
Product coverage
One contract per product. One set of rules.
ApexAPI is not a gateway in front of the products, and it is not a new execution engine. Each product owns its contract; the rules below apply to every one.
| Product | Implemented operations | Scopes | Direction |
|---|---|---|---|
| ScrawlBuilt |
|
|
|
| CommunicationsBuilt |
|
|
|
| DevOpsPlanned | No customer contract yet | Not defined yet |
|
Request lifecycle
What happens to every call.
The transport never becomes the authority. Every request is authenticated, scoped, validated, and put through product policy before anything runs.
- 01Authenticate the caller
- 02Check the scope
- 03Validate the typed request
- 04Apply product policy
- 05Execute or queue
- 06Return an ID and state
- 07Read results and history
Mutations and retries
Retry safely. Send once.
Networks drop responses, and a client that cannot tell whether a send happened will retry. Communications requires an Idempotency-Key on every send and stores the outcome durably, so a retry replays the result instead of messaging a customer twice. Scrawl accepts the same header on every submit, so a retried scrape or crawl never runs twice.
| Request | Outcome |
|---|---|
| First request with a new key | The operation runs once and its result is stored against the key. |
| Retry with the same key and body | The stored result is returned, marked as a replay. Nothing is sent twice. |
| Same key, different body | Rejected with idempotency_conflict, so a reused key cannot silently mean something new. |
| Retry while the first is still running | Rejected with idempotency_in_progress; retry after a short wait. |
Errors
Errors a program can branch on.
Failures come back as stable, machine-readable codes with the matching HTTP status, so a client decides whether to retry, fix the request, or stop—without parsing prose. Shown: the Communications error vocabulary.
| Code | HTTP | Meaning |
|---|---|---|
authentication_failed | 401 | The credential is missing, unknown, or revoked. |
insufficient_scope | 403 | The credential is valid but lacks the operation's scope. |
resource_not_found | 404 | No such record for this caller. |
validation_error | 422 | The typed request failed validation. |
trust_safety_denied | 422 | The product's policy refused this send. |
insufficient_credits | 402 | The account or workspace has no allowance left for this work. |
idempotency_conflict | 409 | The key was already used for a different request. |
idempotency_in_progress | 409 | The first request with this key has not finished. |
rate_limited | 429 | Too many requests; Retry-After says when to try again. |
provider_failure | 502 | The workspace's provider rejected or failed the call. |
internal_error | 500 | An unexpected failure inside the product. |
Scrawl API
Scrape, crawl, and query. Results you can cite.
Built
Scrape and map calls answer within a bounded wait or hand back the job to collect later; crawls and other jobs return 202 Accepted with a job ID. Every job runs through the same gate as any Telegram or agent request, reads are limited to what the credential's owner owns, and every submit accepts an Idempotency-Key. Extraction and answers run on the caller's own AI provider. Representative routes:
POST/v1/scrapeGET/v1/scrape/{job_id}/contentPOST/v1/mapPOST/v1/scrape/batchPOST/v1/crawlsGET/v1/jobs/{job_id}POST/v1/jobs/{job_id}/cancelGET/v1/artifacts/{job_id}/{filename}GET/v1/datasets/{dataset_id}/diffPOST/v1/datasets/{dataset_id}/queryPOST/v1/searchPOST/v1/extractPOST/v1/askCommunications API
Describe the communication, not the provider call.
A send names a channel, a contact, and a message or template; a reply names a conversation. The product picks the workspace's provider, applies consent and Trust and Safety, and returns a redacted record. Integrations and agents can be required to prepare first and confirm with a single-use token.
Built
POST/api/v1/communicationsPOST/api/v1/communications/confirmationsGET/api/v1/communications/{communication_id}GET/api/v1/communicationsGET/api/v1/conversationsGET/api/v1/conversations/{conversation_id}POST/api/v1/conversations/{conversation_id}/repliesPOST/api/v1/conversations/{conversation_id}/replies/confirmationsPOST/api/v1/conversations/{conversation_id}/escalatePOST/api/v1/conversations/{conversation_id}/resolvePOST/api/v1/conversations/{conversation_id}/handoffGET/api/v1/media/{token}Request
POST /api/v1/conversations/{id}/replies
Authorization: Bearer <api credential>
Idempotency-Key: reply-7f3a
Content-Type: application/json
{
"body": "It ships today.",
"provenance": "human",
"expected_version": 4
}
When it cannot be sent
409 conversation_owned_by_human
409 conversation_version_conflict
422 conversation_window_closed
422 trust_safety_denied
Conversation checks refuse before anything
is recorded or sent.
DevOps API
Incident state and evidence for software.
Planned
DevOps will give applications the view of an incident its operators have—what was detected, what was decided, what changed, and how it was verified—plus a narrow set of requests. A request can ask the controller to look again or record an operator's decision; it can never name an action, widen policy, or grant authority. A caller can ask; standing policy decides.
No routes, scopes, or schemas are published. The contract will be defined with the managed service. How DevOps will be reached.
Availability and tooling
Real contracts, no invented gateway.
The Scrawl and Communications contracts are built in their products and are not publicly hosted; the DevOps contract is planned. There is no shared public base URL, cross-product SDK, or single sign-on across products; each product issues its own credentials.
The contracts are typed end to end. Scrawl's Python and TypeScript SDKs and its command-line tool are built from its contract and tested against a real Scrawl; they are not published yet.