Get started
.MD
Menu
Tarka/Docs/Control API/Accounts and organizations
AvailableControl API · Organizations

Accounts, organizations, and access requests

Discover the signed-in identity, choose an organization explicitly, and keep product-access requests attached to durable workspace state.

Identity

Discover organization IDs with GET /me

The response contains the authenticated user ID, email, every active organization, each membership role, and default_org_id. The default is the oldest active membership; API callers may select any returned organization.

Active workspace is client state.

The console remembers a selected organization in a browser cookie. The Control API does not mutate a global active organization; put the intended org_id in each route.

Creation

Bootstrap once or create explicitly

BootstrapCurrentUser is idempotent: when the account already has an organization, it returns current state without creating another. CreateOrg always creates an additional organization and makes the caller its owner.

BootstrapPOST /me/bootstrap
curl -X POST "https://tarka.rest/control/v1/me/bootstrap" \
  -H "Authorization: Bearer $TARKA_ACCOUNT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"org_name":"Acme Research"}'
Create organizationPOST /orgs
curl -X POST "https://tarka.rest/control/v1/orgs" \
  -H "Authorization: Bearer $TARKA_ACCOUNT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Acme Production","slug":"acme-production"}'
Name1–120 characters

Human-readable and mutable by an owner or admin.

Slugoptional, immutable

Explicit slugs must be valid and globally unique. When omitted, the service allocates one.

Owner membershipautomatic

The authenticated creator becomes an active owner.

Metadata and membership

Read members and rename safely

Every active member may read organization metadata and the membership list. Only an owner or admin may send PATCH /orgs/{org_id}, and the mutable request field is name.

Invite teammates from the organization’s Members section.

Owners and admins can send, resend, and revoke email invitations. Choose member, viewer, or operator; only owners may invite admins. Links expire after seven days, and resending invalidates the old link. Recipients sign in or create an account and verify the invited email before accepting. Invitations grant organization membership; platform and product access still require approval.

The Control API exposes POST /orgs/{org_id}/invitations, GET /orgs/{org_id}/invitations, and DELETE /orgs/{org_id}/invitations/{invitation_id}. Create accepts email and role and returns a one-time token for your trusted email delivery service. The console delivers the email automatically. Send the token in a JSON body to POST /org-invitations/preview or POST /org-invitations/accept as the verified recipient. These two routes also allow pending accounts without granting platform approval. Tokens must never be logged or placed in query strings.

Role changes, member removal, ownership transfer, and organization deletion are not yet supported.

By request

Submit and inspect product-access requests

Use this lifecycle to request a product your account is not approved for yet. The authenticated email is used when contact_email is empty. Requests accept the canonical products inference, utilities, agents, jobs, sandboxes, storage, and git.

Request Agent Hosts200 OK
curl -X POST \
  "https://tarka.rest/control/v1/orgs/$TARKA_ORG_ID/product-access-requests" \
  -H "Authorization: Bearer $TARKA_ACCOUNT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "product":"agents",
    "product_detail":"agent_hosts",
    "use_case":"Run a long-lived research agent"
  }'
Product access requestsubmitted
{
  "id": "0edc3d5f-...",
  "org_id": "9df4f7b1-...",
  "user_id": "7cb5a20b-...",
  "product": "agents",
  "product_detail": "agent_hosts",
  "contact_email": "owner@example.com",
  "company": "",
  "use_case": "Run a long-lived research agent",
  "status": "submitted",
  "created_at": "2026-08-30T14:00:00Z",
  "updated_at": "2026-08-30T14:00:00Z"
}

List requests with GET /orgs/{org_id}/product-access-requests. Add ?product=agents to filter and &limit=100 to raise the default limit of 25. Results are newest first and the limit is capped at 100.

A submitted request is not an entitlement.

Wait until Tarka approves and activates the matching product entitlement before calling that product's provisioning operations.

Reference

REST routes

Prefix every path with https://tarka.rest/control/v1.

MethodPathAbility
GET/meReturn identity and active organizations
POST/me/bootstrapCreate the first organization only when none exists
POST/orgsCreate an additional organization
GET/orgs/{org_id}Read one visible organization
PATCH/orgs/{org_id}Rename an organization
GET/orgs/{org_id}/membersList memberships
POST/orgs/{org_id}/product-access-requestsSubmit a product-access request
GET/orgs/{org_id}/product-access-requestsList newest product-access requests