Tarseek API · Pre-production

Project controls

Reusable policies

The Policies page lets project owners and admins save restrictions and assign them to the whole project or selected API keys. Members can inspect the combined preview. An unassigned policy is a draft. Edits use revision checks and are audited.

Model, provider and hosted-tool allowlists intersect; an empty restricted list blocks all. Lower token-price ceilings win, and any policy can prohibit tool writes or optional response caching, or require verified model-provider no-collection support. Budgets and rate limits still apply. These controls do not classify harmful content or guarantee external-tool retention practices.

Rules are checked before model admission and cache lookup, and again before tool dispatch. Changes affect future admission; they cannot recall a request already sent. Token-price ceilings are not per-image or per-second spending caps.

Full-response caching

Opt in using X-Tarseek-Cache: true or cache_enabled: true. Set X-Tarseek-Cache-TTL (or cache_ttl_seconds) to 1–86400 seconds; the default is 300. Invalid headers fail explicitly. X-Tarseek-Cache-Clear: true refreshes the matching entry.

Text and client-tool responses support both JSON and streaming replay. A hit has a fresh request ID, zero billable usage and no inference charge. Response headers identify HIT, MISS or BYPASS, remaining TTL and the source request ID. Entries are encrypted and isolated by project, API credential, endpoint format and normalized request. Rotation or changes to eligible provider credentials produce a miss. Errors and partial streams are never stored.

Opting in stores the generated response for the TTL. Prompts are hashed, not stored. Entries expire on their own. Responses over 1 MiB are not stored, and a project keeps at most 128 entries.

Explore and compare usage

Usage includes two-dimension exploration, exact filters, hourly/day buckets, preceding-period comparisons, request drill-downs and CSV export. Save private views or share them as a manager. Saved dates remain fixed until you change them.

Tag requests with attribution: {"application":"support-app","agent":"triage","user":"opaque-123"}. Labels are limited to 64 identifier characters. Use opaque values, never personal information. Application and agent labels remain readable; user and session identifiers are stored as project-scoped hashes. Attribution is not forwarded to providers.

For automation, management credentials with analytics:read can call /v1/management/projects/PROJECT_ID/analytics/meta and POST /analytics/query. Query fields are start/end (UTC timestamps), group_by (up to two dimensions), granularity (none/hour/day), filters, compare, sort (cost/requests) and limit (up to 100). Date ranges are limited to 90 days, or seven for hourly views. Missing costs and tokens are disclosed with sample counts; incomplete totals do not receive a percentage-change claim.

Notifications and communications

Each project keeps in-app alerts and per-member email for budget thresholds, model retirement, failed batches, API limits, and provider-key changes. Budget, model retirement, and failed jobs start enabled. Managers can send the same events to one HTTPS webhook.

Verification, password reset, data-export, and a password-change security notice are always sent. Product updates and news can be turned off in Account Settings. Tarseek is not sending that optional mail yet.

Webhook delivery is at least once. Deduplicate event IDs. Failed payloads expire after seven days; delivery history is kept for 30 days.

Team and management access

Settings supports email invitations, member removal, administrator roles and ownership transfer. Only owners can change administrators. Each invitation is bound to the recipient’s verified email, expires after seven days, and can be resent or cancelled by a project manager.

Ownership changes require recipient acceptance and no active requests. Existing Tarseek API keys, provider credentials and trace delivery are disabled for review. Team changes and API-key changes appear in the manager-only audit history.

Create separate management credentials in Settings for keys:read, keys:write or analytics:read. They expire in at most one year and cannot run models. Use Bearer authentication at /v1/management/projects/PROJECT_ID/keys to list/create keys, /KEY_ID to read/update/delete, and /KEY_ID/rotate to rotate. Create and rotate require an Idempotency-Key. Scope, current manager role and revocation are checked on every request.

Permissions and spending

API keys support inference, models:read, files:read, files:write and requests:read permissions. File references inside inference require files:read. Existing keys retain their permissions; new dashboard keys default to inference and model discovery. Rotation preserves scopes.

Optional project budgets use UTC calendar months and compare catalog-estimated cost against recorded usage before dispatch. Leaving the limit empty disables the budget. These controls are Tarseek-side guardrails and do not cap or replace limits on your provider account. Lowering a budget does not cancel work already admitted.

Manage budgets and the alert inbox on the API keys page. Monthly budget thresholds and model retirements are checked for models the project used recently. Matching events are also emailed or sent to the project webhook when those channels are enabled.

Your provider keys

Managers can configure one encrypted key per direct OpenAI, Anthropic, or Google provider and rotate or disable it. A customer key is required for model execution; the provider bills the customer account directly.

Each project provider key has isolated quota and health state. Saving a secret does not verify it with the provider; the next request does. Tarseek never falls back to a platform-owned credential.

Prompt caching

Chat and Messages accept cache_control with ephemeral type and 5m or 1h TTL, including text-block breakpoints. Explicit controls require a native Anthropic deployment with verified cache-write pricing; 1h additionally requires a matching TTL price rule. All breakpoints in one request must use the same TTL. Provider minimum prompt lengths still apply.

Pass an opaque session_id to associate conversation turns for cache accounting. Keys and projects are isolated. Cache read/write tokens and estimated net savings appear in request details. Savings compare catalog rates and are estimates; writes can cost more than uncached input.

Historical usage and exports

Usage history is built from completed requests in durable UTC hourly aggregates. The dashboard shows pending work and the last update. Daily views support 366 days, hourly views 31 days, with bounded dimensions. Model filters select the requested model.

CSV request exports support up to 31 days and 10,000 requests and contain metadata only. Larger exports fail with instructions to narrow the query. Aggregate exports wait until the selected window has no pending requests. CSV values are escaped for spreadsheet safety.

Management API

Dashboard session authentication and project membership protect these endpoints; owners/admins manage changes. They are not authenticated with inference keys.

GET /v1/projects/{id}/usage/history
GET /v1/projects/{id}/exports/requests
GET /v1/projects/{id}/exports/usage
GET, PUT /v1/projects/{id}/budget
GET /v1/projects/{id}/alerts
POST /v1/projects/{id}/alerts/{alert_id}/acknowledge
GET /v1/projects/{id}/provider-keys
GET /v1/projects/{id}/provider-keys/providers
PUT /v1/projects/{id}/provider-keys/{provider_id}