API Reference

{
  user_id: string;   // required, 1-255 chars, not a reserved identifier
  role?: "user" | "dashboard-service" | "admin";  // default: role on the API key
  ttl?: number;      // seconds, 60-86400, default 3600
  tier?: string;     // optional tier name; injected as a JWT claim
}

{
  access_token: string; // RS256 JWT
  token_type: "Bearer";
  project_id: string; // UUID
  expires_in: number; // seconds
}

curl -X POST https://api.behest.app/auth/v1/auth/mint \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer behest_sk_live_abc123..." \
  -d '{"user_id": "user-123", "ttl": 3600}'

const resp = await fetch("https://api.behest.app/auth/v1/auth/mint", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${apiKey}`,
  },
  body: JSON.stringify({ user_id: userId, ttl: 3600 }),
});
const { access_token, expires_in } = await resp.json();

{
  keys: Array<{
    kty: "RSA";
    n: string;
    e: string;
    kid: string;
    use: "sig";
    alg: "RS256";
  }>;
}

curl https://api.behest.app/.well-known/jwks.json

{
  name: string; // required
}

{
  id: string; // UUID
  name: string;
}

curl -X POST https://api.behest.app/auth/v1/tenants \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <session-token>" \
  -d '{"name": "Acme Corp"}'

Array<{
  id: string;
  tenant_id: string;
  name: string;
  slug: string;
  status: string; // "active" | "suspended"
  dns_status: string; // "PENDING" | "READY" | "FAILED"
  created_at: string; // ISO 8601
}>;

curl https://api.behest.app/auth/v1/tenants/<tenantId>/projects \
  -H "Authorization: Bearer <session-token>"

{
  name: string; // required
}

{
  id: string;
  tenant_id: string;
  name: string;
  slug: string; // e.g. "amber-fox-042" — auto-generated
  fqdn_dev: string; // "{slug}.dev.internal.behest.ai"
  fqdn_prod: string; // "{slug}.behest.app"
  dns_status: "PENDING";
}

curl -X POST https://api.behest.app/auth/v1/tenants/<tenantId>/projects \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <session-token>" \
  -d '{"name": "Support Chatbot"}'

{
  dns_status: "PENDING" | "READY" | "FAILED";
  dns_last_error: string | null;
  fqdn_dev: string;
  fqdn_prod: string;
  slug: string;
  dns_updated_at: string | null; // ISO 8601
}

{
  dns_status: "PENDING";
}

{
  status: "suspended";
}

{
  id: string;
  project_id: string;
  system_prompt: string | null;
  memory_window: number;               // 0-500, default 50
  cors_origins: string[];
  cors_allow_credentials: boolean;
  rpm_limit: number;                   // 1-10000, default 60
  tokens_per_day: number;              // min 1000, default 1000000
  pii_mode: "disabled" | "shadow" | "enforce";
  pii_entities: Record<string, "MASK" | "REDACT" | "BLOCK">;
  sentinel_mode: "disabled" | "shadow" | "enforce";
  sentinel_blocklist: string[];        // max 200 terms
  memory_enabled: boolean;
  retention_days: number | null;       // 1-365
  store_tool_calls: boolean;
  provider_model: string | null;       // deployed model
  draft_provider_model: string | null; // unsaved model draft
  draft_saved_at: string | null;
  deployed_at: string | null;
  created_at: string;
  updated_at: string;
}

{
  system_prompt?: string;          // max 32000 chars
  memory_window?: number;          // 0-500
  cors_origins?: string[];         // each must be "scheme://host" with no trailing slash, or "*"
  cors_allow_credentials?: boolean; // cannot be true when cors_origins includes "*"
  rpm_limit?: number;              // 1-10000
  tokens_per_day?: number;         // >= 1000
  pii_mode?: "disabled" | "shadow" | "enforce";
  pii_entities?: Record<string, "MASK" | "REDACT" | "BLOCK">;
  sentinel_mode?: "disabled" | "shadow" | "enforce";
  sentinel_blocklist?: string[];   // max 200 terms
  memory_enabled?: boolean;
  retention_days?: number | null;  // 1-365 or null
  store_tool_calls?: boolean;
  provider_model?: string | null;  // known model ID or null; saved as draft
}

{
  deployed: true;
  project_id: string;
  deployed_at: string; // ISO 8601
}

{
  provider_model: string; // required, must be a known model ID
}

{
  configured: true;
  provider_model: string;
  provider_type: string; // e.g. "openai", "anthropic"
}

{
  provider_model: string;
}

{
  draft_provider_model: string | null;
  draft_saved_at: string | null;
}

{
  provider_model: string;
  deployed_at: string;
}

Array<{
  id: string;
  name: string | null;
  role: string;
  prefix: string; // first 8 chars of the key's SHA-256 lookup hash + "…"
  createdAt: string; // ISO 8601
}>;

{
  name?: string;  // default "default"
}

{
  id: string;
  project_id: string;
  api_key: string; // "behest_sk_live_..." — shown once only
  message: string; // "Store this key securely. It will not be shown again."
}

curl -X POST https://api.behest.app/auth/v1/projects/<projectId>/api-keys \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <session-token>" \
  -d '{"name": "production"}'

{
  id: string;
  api_key: string; // new plaintext key — shown once only
  message: "New key generated. Old key is revoked.";
}

{
  message: "API key revoked";
}

{
  message: "API key revoked";
}

{
  providers: Array<{
    provider_type: string; // "openai" | "anthropic" | "google" | "openrouter" | "mistral" | "cohere"
    key_last4: string; // last 4 chars of the original key
    key_set_at: string; // ISO 8601
    projects_using_count: number; // how many projects in this tenant use this provider's models
  }>;
}

{
  provider_types: string[];  // e.g. ["openai", "anthropic"]
}

{
  api_key: string;           // required — the provider API key
  base_url_override?: string; // optional custom API base URL (SSRF-safe validation applied)
}

{
  configured: true;
  provider_type: string;
  key_last4: string;
  key_set_at: string; // ISO 8601
}

curl -X PUT https://api.behest.app/auth/v1/tenants/<tenantId>/providers/openai \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <session-token>" \
  -d '{"api_key": "sk-proj-abc123..."}'

{
  api_key: string;
}

{
  valid: boolean;
  reason?: "invalid_key" | "network_error" | "timeout" | "rate_limited";
}

{
  models: Array<{
    modelId: string;
    displayName: string;
    providerSlug: string;
    providerDisplayName: string;
    capabilities: Record<string, unknown>;
    contextWindow: number | null;
    maxOutputTokens: number | null;
    supportsStreaming: boolean | null;
    supportsToolUse: boolean | null;
    supportsVision: boolean | null;
  }>;
}

Array<{
  id: string;
  project_id: string;
  name: string;
  sort_order: number;
  overrides: Record<string, unknown>;
  resolved: Record<string, unknown>; // project defaults merged with tier overrides
  created_at: string;
  updated_at: string;
}>;

{
  name: string;                          // required, unique per project
  sort_order?: number;                   // default 0
  overrides?: {                          // all optional
    rpm_limit?: number;
    tokens_per_day?: number;
    pii_mode?: "disabled" | "shadow" | "enforce";
    pii_entities?: Record<string, "MASK" | "REDACT" | "BLOCK">;
    sentinel_mode?: "disabled" | "shadow" | "enforce";
    sentinel_blocklist?: string[];
    memory_enabled?: boolean;
    memory_window?: number;
    retention_days?: number | null;
    store_tool_calls?: boolean;
    provider_model?: string;
    system_prompt?: string;
  };
}

{
  project_id: string;
  memory_enabled: boolean;
  memory_window: number;
  retention_days: number | null;
  system_prompt: string | null;
  store_tool_calls: boolean;
}

{
  messages: Array<{ role: string; content: string }>;
}

{
  enabled: boolean;
}

{
  killswitch: "global";
  enabled: boolean;
}

{
  killswitch: "tenant";
  tenantId: string;
  enabled: boolean;
}

{
  killswitch: "project";
  projectId: string;
  enabled: boolean;
}

{
  global: boolean;
  tenants: string[];   // tenant IDs with kill switch enabled
  projects: string[];  // project IDs with kill switch enabled
}

{
  providers: Array<{
    id: string;
    name: string;
    slug: string;
    display_name: string;
    is_active: boolean;
    model_count: number;
    created_at: string;
    updated_at: string;
  }>;
}

{
  name: string;                     // required, unique
  slug: string;                     // required, unique
  displayName: string;              // required
  modelsEndpointUrl?: string;
  modelsEndpointAuthType?: string;
  authConfigSchema?: object;
  supportedFeatures?: object;
}