Developer Glossary

A bearer credential prefixed with intelligence_ that authenticates requests to the Orbyt Intelligence API. Created from the dashboard's Keys tab. Encrypted at rest with AES-256-GCM (PBKDF2-derived). Each key is tied to a tier and a set of scopes. Treat as a secret: server-side only, never bundle into client code.

The HTTP authentication scheme used by the Orbyt API. Every request sends the API key in the Authorization header as Bearer <key>. Per RFC 6750. Bearer tokens are validated server-side against the encrypted store; an invalid or expired key returns 401 authentication_invalid in the locked error envelope.

A check applied to state-changing requests (POST, PATCH, DELETE) that the request's Origin or Referer header matches the configured NEXT_PUBLIC_APP_URL. Rejects cross-site request forgery (CSRF) attempts. Skipped in dev mode and for requests from localhost. The verifyOrigin helper at app/api/_lib/rate-limit.ts implements this.

A capability flag attached to an API key that controls which endpoints it can call. Examples: intelligence:read, skills:read, market:read, compensation:read, company_data:read, intelligence:lineage, intelligence:write. Scopes are checked per-route via the ROUTE_SCOPE_REQUIREMENTS registry. A missing scope returns 403 scope_insufficient with the list of missing scopes.

The pricing tier attached to an API key. Build is the entry tier at $99/month with 60 requests per minute. Pro at $299/month adds 300 req/min plus skill premiums, half-life, comp-by-stage, hiring velocity, MCP, and lineage. Scale at $1,999/month adds company signals plus webhooks at 1,500 req/min. Enterprise at $4,999/month tops out at 5,000 req/min with custom invoicing.

The locked shape every error response returns: {error: {type, code, param?, message, doc_url, request_id, retry_strategy, retry_hint?, follow_up_suggestions?}}. Locked by RFC-001 for the life of v1. Codes are permanent: new error situations get new codes, existing codes are never deleted. Always check error.code before error.message.

The locked shape returned by collection endpoints: {data: [...], pagination, attribution, request}. The pagination block contains cursor markers for the next page. The attribution block carries methodology_version, sample size, and source breakdown for every list item. Locked by RFC-001.

A unique identifier returned on every response (success or error) as both a JSON field and an X-Request-Id header. Format: req_<16hex>. Generated at the edge in proxy.ts and propagated through. This is the searchable key for the customer log explorer at /intelligence/dashboard?tab=logs and the Sentry distributed-tracing tag.

The locked shape returned by single-resource endpoints: {data, attribution, request}. The attribution block carries methodology_version, sample size, confidence interval, source breakdown, and the data_point_id for lineage lookups. The request block carries request_id and duration_ms. Locked by RFC-001 for the life of v1.

A universal query parameter that replays a calculation against a historical snapshot. Allowed range starts at 2024-07-01 and ends today plus one day. Combine with any other query params to get a snapshot-frozen answer. Locked grammar per RFC-002 §B4. Available on every numeric endpoint.

Stripe-compatible pagination via ?limit, ?starting_after, and ?ending_before. Returns a pagination block with has_more and the next cursor. Cursors are opaque strings derived from the last item's sort key. Stable under inserts: a new row appearing during pagination doesn't shift the cursor window. Locked by RFC-002 §2.

A query parameter (?expand[]=path) that inlines a related resource into the response. Stripe-compatible pattern. Each path declares its min_tier, required_scopes, and status in the expand-bootstrap registry. Multiple expands cache-key together via expandHash. Locked by RFC-002 §5.

A query parameter (?fields=path1,path2) that lets the client select which response fields to return. Reduces payload size and bandwidth. Reserved parameter names (limit, starting_after, expand, sort, as_of, etc.) are filtered automatically. Locked by RFC-002.

Universal filter syntax: ?field=v1,v2 (OR within field), or ?not_field=value (exclusion). Endpoints declare which fields are filterable via a whitelist; unknown filters return 400 invalid_parameter. Stackable: multiple filter fields combine as AND. Locked by RFC-002 §3.

Universal sort syntax: ?sort=field&order=asc|desc. Endpoints declare which fields are sortable via a whitelist; unknown sort fields return 400 invalid_parameter. Default order is descending on the canonical date field. Locked by RFC-002 §4.

A client-supplied header on POST endpoints that makes retries safe. Format: 8 to 200 characters from [A-Za-z0-9_-]. Same key plus same body within 24 hours returns the original response with X-Idempotent-Replayed: true. Same key plus different body returns 409 idempotency_key_conflict. Stripe-compatible. 5xx responses are never cached.

A per-tier cap on requests per minute. Build 60/min, Pro 300/min, Scale 1,500/min, Enterprise 5,000/min. Counted server-side via Upstash Redis with a sliding window. Each response includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers. Exceeding the cap returns 429 rate_limit_exceeded with a Retry-After header.

A field on every error envelope that tells the client whether and how to retry. Values: none (do not retry), exponential_backoff (retry with backoff), retry_immediately (idempotent retry safe), wait_and_retry (wait the suggested time). The retry_hint field accompanies wait_and_retry with a target seconds value.

A measurable latency target for an endpoint: p50, p95, p99 latency thresholds plus error_rate_max and availability percentages. Declared per-route in app/api/v1/intelligence/_lib/slo.ts ROUTE_SLOS. Phase 5's customer /status page renders live performance vs each SLO. Adding a new route without an SLO entry leaves it un-budgeted.

The locked output shape every MCP tool returns: {answer, data: {primary, supporting}, context: {methodology_version, sample_size, confidence_*, source_breakdown, disagreement_flag}, citation: {methodology_url, data_point_id, corrections_url, request_id}, follow_up_suggestions, limitations, cache_ttl_seconds}. Locked by RFC-004 §3. Designed so an LLM agent can quote the answer with full citation support.

The wire protocol for MCP. Every request is a JSON envelope {jsonrpc: "2.0", id, method, params}. Every response is either {jsonrpc, id, result} or {jsonrpc, id, error: {code, message, data?}}. Notifications omit the id and produce no response. Spec at jsonrpc.org/specification.

An open standard from Anthropic for letting LLM agents call external tools through a structured JSON-RPC interface. Orbyt ships a 6-tool MCP server: analyze_compensation, analyze_skills, analyze_market, discover_roles_and_cities, find_adjacent_opportunities, list_capabilities. Locked tool surface per RFC-004 §2. Pro tier and above.

A single callable function exposed through the MCP server. Each tool declares its inputSchema (JSON Schema), required tier, required scopes, and output_shape (always "decision-ready-response" for v1). Tool names are locked: list_capabilities, analyze_compensation, analyze_skills, analyze_market, discover_roles_and_cities, find_adjacent_opportunities. New tools may be added; existing tools are never renamed.

The cryptographic mechanism used to verify webhook authenticity. Orbyt signs every webhook payload with HMAC-SHA256 using a shared secret, sending the signature in the X-Orbyt-Signature header. Verify on receipt with crypto.timingSafeEqual. Stripe-compatible pattern. Sample verification code in 5 languages on the webhooks reference page.

A server-to-server notification posted to a customer-registered URL when a relevant event occurs. Event types include data.refreshed, methodology.bumped, lineage.corrected, snapshot.frozen, and key.rotated. Each event carries a typed payload, an event_id (deduplication key), an event_version, and a created_at timestamp. Scale tier and above.

Orbyt retries failed webhook deliveries with exponential backoff. Retry attempts: 1 minute, 5 minutes, 30 minutes, 2 hours, 12 hours, then dead-letter. Idempotent on event_id so safely re-deliverable. Failed deliveries are surfaced in the customer dashboard. Tunnel through Orbyt CLI in dev for local testing.