AvailableControl API

Provision and manage Tarka

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

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 instead.

RESThttps://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

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

Control API

MCP for AI assistants

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

Control API

Inference capture

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

Control API

Identity and organizations

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

Control API

Keys, policy, and usage

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

Control API

Provisioned resources

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

Control API

Code Sandboxes

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

Control API

Object Storage and Git

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

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 basehttps://tarka.rest/control/v1

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

Native gRPCgrpc.tarka.rest:443

Use tarka.provisioning.v1.ProvisioningService and SandboxService.

Machine contracttarka-control-v1.swagger.json

Open the generated Swagger document →

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 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.