API reference

Base URL and conventions

https://edge.vindexgateway.com

• JSON only. All requests and responses use application/json, except file uploads which use multipart/form-data.
• UTC timestamps. All dates are ISO 8601 in UTC.
• Customer ID scoping. Every ticket you submit is tagged with the customer_id you were assigned when your integration was provisioned. Scores are only visible to that customer and to your linked company.
• Standard HTTP codes. 2xx for success, 4xx for client errors, 5xx for server errors. Error bodies include a detail field describing what went wrong.

Authentication

Authenticated endpoints take an API key as a bearer token. A Client Admin creates keys in the Vindex portal under API keys(a Vindex Admin can do it from the company page), names each one for the agent or system that will use it, and can show or revoke it at any time. The same key works for Vindex MCP when an agent can't sign in with OAuth. Pass it on every request:

Authorization: Bearer <your_api_key>

The /evaluate/* endpoints that power the public CSV flow are unauthenticated but rate-limited per IP; see the evaluate reference for limits.

Synchronous vs. asynchronous scoring

Vindex exposes the scoring engine in two shapes. Pick whichever fits how your integration is wired; both run the identical INVEST analysis and return the same dimensions.

See the evaluate reference for full request and response payloads for both models.

Endpoint groups

Rate limits

The monthly quota counts new unique stories: re-scoring a story that has already been counted is free forever and is admitted even when the quota is exhausted. When a new story is refused, the response is 429 with code: "QUOTA_EXHAUSTED" and a machine-readable body:

{
  "error": "Quota exhausted",
  "code": "QUOTA_EXHAUSTED",
  "message": "The monthly story quota is reached. New stories are paused until the quota resets; previously scored stories can still be re-scored at no cost.",
  "plan": "starter",
  "quota": 200,
  "used": 200,
  "reset_at": "2026-09-01T00:00:00Z",
  "upgrade_url": "https://register.vindexgateway.com/portal",
  "already_counted": false
}

Per-IP limits on the public CSV endpoints return 429 Too Many Requests with a Retry-After header. Distinguish quota exhaustion by the code field, never by the status alone.

Story identity & billing

Billing is per unique story, once. Send a stable external_id with each request (your own record id) and every later score of that id is a free re-score, in any month. Without an external_id, Vindex falls back to a normalized fingerprint of the story's content: unchanged content stays free, edited content bills as a new story. Responses disclose the applied rule in identity_resolution (external_id or content_hash) and echo the resolved story_identity, so the billing unit is always visible at the point of use.

Error shape

Statistics endpoints (/stats/*) return every error in one envelope, with nothing else in the body:

{
  "error": {
    "code": "DATE_RANGE_TOO_LONG",
    "message": "The date range cannot be longer than 365 days.",
    "request_id": "req_2f9c1a7e4b8d4c0f9a3e6d5b7c1f2a3b"
  }
}

Branch on code, never on message: codes are stable, and each always comes with the same HTTP status. The same request_idis returned in theX-Request-Idheader on every response. Include it when you contact support.

Scoring endpoints (/api/v1/*) still use their earlier error body:

{
  "error": "Validation failed",
  "message": "Invalid request format",
  "details": ["Missing required fields: ticket_id or ticket_data"]
}

The unauthenticated CSV endpoints (/evaluate/*) are served directly by the scoring backend and use the framework default shape instead:

{
  "detail": "CSV must have at least 2 columns"
}