Developers

Connect your application to the model.

Use the service’s generated OpenAPI contract to map your application data to the workbook’s inputs. Send a JSON request with a scoped API key and receive the calculated outputs, the model version and a request ID. Your integration handles validation errors as part of the calling workflow.

Evaluate

One call per calculation.

Use your installation’s API hostname. Authenticate with an API key, post the inputs and read the outputs. The example is illustrative.

Request

shell

curl https://xsheet.example.internal/v1/evaluate/auto-rating \
  -H "Authorization: Bearer $XSHEET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"inputs": {"State": "WY", "VehicleAge": 4}}'

Response

200 OK

{
  "request_id": "req_01j9x4…",
  "service": "auto-rating",
  "environment": "production",
  "version": { "id": "ver_01j8…", "number": 12 },
  "outputs": { "FinalPremium": 1284.5 }
}

Endpoints

A small, stable surface.

The data plane is small on purpose. New capabilities arrive as optional fields, and every change to the API description is checked for breaking changes before it is merged.

Endpoints of the evaluation API
Method	Path	Purpose
POST	/v1/evaluate/{service}	Evaluate the service with the given inputs
GET	/v1/services	List the services the key may call
GET	/v1/services/{service}	Describe a service: its inputs and outputs
GET	/v1/services/{service}/openapi.json	The service’s typed contract as OpenAPI
GET	/v1/openapi.json	The OpenAPI description of the API

Contract

Strict inputs, typed outputs.

Every service publishes its contract as JSON Schema inside an OpenAPI 3.1 description.

Unknown fields are rejected, and every invalid field is reported at once with a JSON pointer (422).
Outputs are typed: numbers, text, logical values, tables and matrices. Excel errors are data, such as {"error": "#N/A"}.
Ask for only the outputs you need with an outputs list in the request.
Pass your own identifiers in meta. They are kept for correlation next to XSheet’s own request ID.
Successful evaluations carry Server-Timing with queue and total durations, plus the calculation time where it is available. These measurements help separate time in the queue from the calculation itself.

Errors

Problem details, with a request ID.

Every error the API answers is an RFC 9457 problem details document with a stable code; errors from the API carry its request ID.

A missing, malformed, expired or revoked key is 401.
A key used outside its environment, allowed networks or scopes is 403.
Rate limits and quotas answer 429 with Retry-After and RateLimit headers.
A service outside the key’s scope answers 404, so a key cannot be used to discover other services.

Problem, shortened

application/problem+json

{
  "title": "Invalid request",
  "status": 422,
  "code": "invalid_request",
  "request_id": "req_01j9x5…",
  "errors": [
    {
      "pointer": "/inputs/VehicleAge",
      "code": "constraint_violation",
      "detail": "…"
    }
  ]
}

API keys

Keys that do one job.

Keys are created in the application, shown once and belong to exactly one environment.

Each key has scopes (evaluate, read), optional limits to certain services and networks, a rate limit, a daily quota and an expiry of 30 days, 90 days, a chosen date or none. A key can be rotated with a grace period, so callers switch without downtime.

Every response from the API, errors included, carries a request ID such as req_01j9x4…. Use it to find the call, its receipt and, while they are retained, its inputs in the application.

Reference

The full reference is in the application.

The complete reference, including each service’s OpenAPI description, is available to invited users after they sign in.

XSheet

See how your model would work as an API.

Discuss the workbook your team maintains and the applications that need its results. Explore integration and deployment in your environment.

Request a demo Deployment