API reference

The Vindex HTTP API covers registration, ticket evaluation, score callbacks, and aggregate stats. It's the same API the Jira Forge app uses — build directly on it to wire story health scoring into whatever tooling your team already relies on.

Base URL and conventions

base url

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 use the bearer token issued to your account when your integration is provisioned. Pass it on every request:

http

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.

Synchronous

POST /v1/score blocks until scoring finishes and returns the full score in the response body. Best for request/response contexts — CI checks, scripts, and the CSV evaluator. No callback endpoint required.

Asynchronous

POST /api/v1/evaluate/{source} acknowledges immediately with 202 and delivers the completed score to your webhook. This is what the Jira Forge app uses.

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

Endpoint groups

Evaluate

Submit a ticket (or a CSV of tickets) for INVEST evaluation. The scoring engine runs asynchronously and delivers results via callback.

Open reference

Callbacks

Receive completed scores at your own webhook endpoint. Verify the signature, handle retries, and store results in your own system.

Open reference

Stats

Read aggregate story health data — averages, trends, and per-dimension breakdowns — programmatically.

Open reference

Rate limits

Endpoint group	Limit	Window
/v1/score	60 requests	1 minute
/evaluate/upload	10 requests	1 hour (per IP)
/evaluate/score	5 requests	1 hour (per IP)

Responses that exceed the limit return 429 Too Many Requests with a Retry-After header.

Error shape

Standard error body

json

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