---
title: ARKEN public API
description: REST API and MCP integration reference
canonical: https://usearken.com/docs/api
last-updated: 2026-10-15
---

# ARKEN Public API

Base URL: https://usearken.com. The public API and MCP tools require no API key.

## SDK availability and quickstarts

ARKEN provides an official CLI and JavaScript and Python SDKs as versioned downloads, plus a published Go module. Registry publication is pending for npm and PyPI. See [ARKEN SDKs and CLI](https://usearken.com/docs/sdk) for installation, examples, checksums, and release status. Use HTTP directly or an MCP client if preferred. These read-only examples search the public catalog without credentials, creating a case, sending mail, or running a model. Run the TypeScript example server-side with a runtime that provides fetch and AbortSignal.timeout. The Python example uses only the standard library.

### TypeScript

~~~typescript
const url = new URL("https://usearken.com/api/v1/deal-types");
url.searchParams.set("q", "breakup");
const response = await fetch(url, { signal: AbortSignal.timeout(10000) });
if (!response.ok) throw new Error("Catalog request failed: " + response.status);
const catalog = await response.json();
console.log(catalog.data);
~~~

### Python

~~~python
import json
from urllib.parse import urlencode
from urllib.request import urlopen

url = "https://usearken.com/api/v1/deal-types?" + urlencode({"q": "breakup"})
with urlopen(url, timeout=10) as response:
    catalog = json.load(response)
print(catalog["data"])
~~~

## Endpoints

- GET /api: API discovery index.
- GET /api/health: service availability.
- GET /api/v1/deal-types?q=breakup: public catalog search. The optional q parameter accepts at most 120 characters. Results contain data and total.
- POST /api/v1/deal-types/batch: read-only catalog search for 1 to 10 queries in one JSON request, such as {"queries":["founder","lease"]}. Results preserve query order.
- POST /ask: NLWeb 0.55 conversational search over the public deal catalog. Send {"query":{"text":"founder breakup"}}; set {"prefer":{"streaming":true}} and Accept: text/event-stream for SSE start, result, and complete events. Results are catalog matches, not generated advice.
- POST /api/v1/case-drafts: prepare an unsaved draft from optional context (up to 20,000 characters) and deal_type (up to 160 characters). Send Content-Type: application/json. The maximum body size is 65,536 bytes.

Example request body: {"context":"Two founders are dividing responsibilities.","deal_type":"Founder breakup"}

Draft results include status=ready, requires_review=true, the context, and the ARKEN URL. This does not persist a case, contact anyone, submit a negotiation, or run analysis.

## Public REST rate limits

Public REST requests use two shared, per-instance fixed windows of one minute: 600 reads per minute across API discovery, catalog, health, OpenAPI, and HTML API documentation; and 60 writes per minute for POST /api/v1/case-drafts. These quotas are shared across callers, not allocated per user or API key.

Responses include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. Reset is the window reset time in Unix epoch seconds. Exhausted quotas return HTTP 429 with the structured API error code RATE_LIMITED and Retry-After in seconds. Wait for that delay before retrying; preserve the same Idempotency-Key when retrying a draft request.

Auth and agent endpoints are excluded from these public REST quotas. Pilot access request endpoints have a separate limiter.

## Idempotency and retries

For POST /api/v1/case-drafts, send an optional Idempotency-Key header with a fresh UUID for each logical request. Reuse it with the same fields on retries. Keys accept 1-128 letters, digits, periods, underscores, colons, or hyphens. JSON formatting and field order do not matter. The server retains key and request hashes for 24 hours, including across restarts, but does not retain draft text. Invalid requests do not reserve a key.

Successful keyed responses include Idempotency-Replayed: false for a new request or true for a matching retry. Different fields with the same key return 409 IDEMPOTENCY_CONFLICT; use the original fields or a new key. A full ledger returns 503 with Retry-After: 60; wait and retry with the same key. Unkeyed requests remain stateless.

## Versioning and deprecation

Public REST paths use a major version in the URL, such as /api/v1. Compatible additions may be made within v1; a change that breaks an existing request or response contract requires a new major path. When an endpoint is scheduled for retirement, its documentation will identify the replacement and the API will send Deprecation and Sunset response headers with the announced dates. No public v1 endpoint is currently scheduled for retirement. See [the versioning policy](https://usearken.com/docs/versioning).

## MCP tools

Connect an MCP client to https://usearken.com/mcp using Streamable HTTP. Use arken_search_deal_types to search, arken_get_deal_type with a returned domain_id to inspect the selected category, and arken_prepare_case for an editable draft. The draft tool can display a native MCP App.

## Errors

Errors contain error.code, error.message, and error.hint. Validation failures include field issues. Status codes include 400 for invalid JSON, query parameters, or idempotency keys, 403 for a disallowed origin, 404 for unknown routes, 405 for unsupported methods, 409 for an idempotency conflict, 413 for oversized bodies, 415 for non-JSON request bodies, 422 for invalid fields, 429 for an exhausted rate limit, and 503 for temporary idempotency capacity. Follow the hint, correct the request, and retry; do not retry unchanged validation failures.

## Further reference

- [OpenAPI contract](https://usearken.com/openapi.json)
- [ARKEN developer resources](https://usearken.com/developers)
- [HTML documentation](https://usearken.com/docs/api)
- [Authentication and availability](https://usearken.com/auth.md)
- [Sign in](https://usearken.com/workspace): create a private workspace with Google sign-in; model analysis requires prepaid credits.
- [Full deal matrix](https://usearken.com/research/contract-comparison#use-case-limits)