---
title: "Control API | Tarka Docs"
description: "Automate Tarka organizations, credentials, policy, usage, compute, storage, Git, and sandboxes through the Control API."
url: "https://tarkahq.com/docs/control-api/"
---

Available Control API

# Provision and manage Tarka

The Control API is the versioned automation surface behind customer workspace state in the Tarka Console.

On this page

[Quickstart](https://tarkahq.com/docs/control-api/#quickstart) [Capabilities](https://tarkahq.com/docs/control-api/#capabilities) [Boundaries](https://tarkahq.com/docs/control-api/#boundaries) [Wire contract](https://tarkahq.com/docs/control-api/#wire-contract) [Errors](https://tarkahq.com/docs/control-api/#errors)

Quickstart

## Call the authenticated account surface

Send an approved Tarka account access token as a bearer token. Start with `/me`, then put the selected `org_id` in every organization-scoped route. From an AI assistant, connect through [MCP](https://tarkahq.com/docs/control-api/mcp/) instead.

REST `https://tarka.rest/control/v1`

```
export TARKA_ACCOUNT_TOKEN="..."

# Discover the authenticated identity and organization IDs.
curl "https://tarka.rest/control/v1/me" \
  -H "Authorization: Bearer $TARKA_ACCOUNT_TOKEN"

# Use an organization ID explicitly on workspace requests.
curl "https://tarka.rest/control/v1/orgs/$TARKA_ORG_ID/resources" \
  -H "Authorization: Bearer $TARKA_ACCOUNT_TOKEN"
```

**An inference key is not an account token.**

A `tk_live_...` key calls the Inference API. Ordinary Control API methods reject it. SandboxService methods are the documented exception when the key has the `sandboxes` scope.

Complete surface

## Choose a capability family

Every durable customer-console mutation is represented here. Product runtime traffic uses its separate data-plane API.

Control API

### [Billing and compute quotes](https://tarkahq.com/docs/control-api/billing-quotes/)

Review prices, accept bounded compute quotes, and inspect optional data usage policy.

[Open reference→](https://tarkahq.com/docs/control-api/billing-quotes/)

Control API

### [MCP for AI assistants](https://tarkahq.com/docs/control-api/mcp/)

Connect Claude or another MCP client with OAuth and use the Control API methods as tools.

[Open reference→](https://tarkahq.com/docs/control-api/mcp/)

Control API

### [Inference capture](https://tarkahq.com/docs/control-api/inference-capture/)

Configure customer capture, expiry, and delivery health through REST, gRPC, or MCP.

[Open reference→](https://tarkahq.com/docs/control-api/inference-capture/)

Control API

### [Identity and organizations](https://tarkahq.com/docs/control-api/organizations/)

Bootstrap an account workspace, create and rename organizations, list members, and submit product-access requests.

[Open reference→](https://tarkahq.com/docs/control-api/organizations/)

Control API

### [Keys, policy, and usage](https://tarkahq.com/docs/control-api/keys-policy-usage/)

Discover models, issue and revoke scoped keys, replace quota policy, and inspect metering.

[Open reference→](https://tarkahq.com/docs/control-api/keys-policy-usage/)

Control API

### [Provisioned resources](https://tarkahq.com/docs/control-api/provisioning/)

Apply inference, Agent Host, and Batch Job desired state and inspect reconciliation status.

[Open reference→](https://tarkahq.com/docs/control-api/provisioning/)

Control API

### [Code Sandboxes](https://tarkahq.com/docs/control-api/sandboxes/)

Build templates, start isolated runtimes, execute source, and retrieve retained output.

[Open reference→](https://tarkahq.com/docs/control-api/sandboxes/)

Control API

### [Object Storage and Git](https://tarkahq.com/docs/control-api/data/)

Provision buckets, S3 credentials, Hosted Git identities, and private repositories.

[Open reference→](https://tarkahq.com/docs/control-api/data/)

API boundaries

## Management is separate from runtime traffic

The console and Control API share durable workspace state. Authentication, operator administration, and product data planes retain separate security boundaries.

| Surface | Endpoint | Responsibility |
| --- | --- | --- |
| **Control API** | `https://tarka.rest/control/v1` | Organizations, access requests, credentials, policy, usage, and resource lifecycle. |
| **MCP server** | `https://tarka.rest/mcp` | The Control API as tools for AI assistants, with OAuth sign-in. |
| **Inference API** | `https://tarka.rest/v1` | Language and utility-model runtime requests with `tk_live_` keys. |
| **Object Storage** | `https://storage.tarka.rest` | S3 object operations with bucket-scoped access and secret keys. |
| **Hosted Git** | `https://git.tarka.rest` | Clone, fetch, and push with SSH keys or personal access tokens. |
| **Account authentication** | `https://tarkahq.com/console/` | Signup, verification, login, recovery, refresh, and logout. |
| **Operator approvals** | Internal console route | Privileged account decisions; intentionally not a customer Control API. |

Contract

## gRPC-first with generated REST bindings

The protobuf service and its `google.api.http` annotations are authoritative. REST and native gRPC invoke the same handlers and authorization checks.

**REST base** `https://tarka.rest/control/v1`

JSON uses protobuf `snake_case` field names. Unknown fields are rejected.

**Native gRPC** `grpc.tarka.rest:443`

Use `tarka.provisioning.v1.ProvisioningService` and `SandboxService`.

**Machine contract** `tarka-control-v1.swagger.json`

[Open the generated Swagger document →](https://github.com/TarkaHQ/api/blob/main/openapi/tarka-control-v1.swagger.json)

Timestamps use RFC 3339. Protobuf JSON may encode 64-bit integers as strings. The request body limit is 2 MiB. Sandbox source, stdin, timeout, and manifest limits are narrower and documented on the Sandbox page.

Errors and retries

## Treat status and machine codes as the contract

Authentication middleware returns a compact `{"error":"code"}` body. Dispatched protobuf errors use the standard gRPC-Gateway status shape.

| HTTP | Meaning | Client action |
| --- | --- | --- |
| `400` | Invalid field or validation limit | Correct the request; do not retry unchanged. |
| `401` | Missing or invalid bearer token | Refresh or replace the account session. |
| `402` | Insufficient funded credit or a spend limit | Review [billing and reservations](https://tarkahq.com/docs/control-api/billing-quotes/) before retrying. |
| `403` | Account, membership, role, entitlement, scope, or organization denied | Resolve access; do not retry unchanged. |
| `404` | Visible resource does not exist | Check the organization and resource ID. |
| `409` | Name conflict or lifecycle precondition | Inspect current resource state. |
| `429` | Quota, rate, or capacity exhausted | Back off and honor the applicable limit. |
| `503` | A required control dependency is unavailable | Retry idempotent reads and idempotent mutations with backoff. |