Skip to main content

API

The API modality is the recommended way to connect your system to Spectral. Spectral sends conversations directly to your endpoint, with no browser or page structure involved.

Your system must expose a publicly accessible POST endpoint. Spectral speaks two protocols over this modality: Chat Completions for plain conversational systems, and the Responses API for agents that call tools. Pick the protocol that matches your endpoint.

Chat Completions​

Expose a POST /v1/chat/completions endpoint that accepts a conversation history and returns the assistant's next reply, following the OpenAI Chat Completions API format.

Request
POST /v1/chat/completions HTTP/1.1
Content-Type: application/json


{
  "messages": [
    { "role": "user",   "content": "What is the capital of France?" },
    { "role": "assistant", "content": "The capital of France is Paris." },
    { "role": "user",   "content": "And of Germany?" }
  ]
}

Spectral reads the assistant reply from choices[0].message.content.

warning

Model parameter not supported: Many /v1/chat/completions implementations require a model field in the request body. Spectral does not include this parameter. Contact us if this is a hard requirement for your setup.

Responses API​

Use the Responses API protocol when your agent calls tools (function calling, retrieval, MCP, code execution). It captures the full sequence of tool calls and their results in a single turn, which is what Spectral evaluates tool-using behavior against.

Expose a POST /v1/responses endpoint following the OpenAI Responses API format. Spectral sends the conversation as an input array and reads the agent's turn from the output array.

Request
POST /v1/responses HTTP/1.1
Content-Type: application/json


{
  "model": "default",
  "input": [
    { "role": "user", "content": "What's the weather in Paris? Should I pack an umbrella?" }
  ],
  "previous_response_id": null
}

Spectral sends the user turn in input. For multi-turn conversations it passes the prior response's id as previous_response_id, so your agent must support response chaining.

Declaring your tools​

When you create or edit a Responses API target, you can declare the agent's tool catalog. In the target wizard's Basics step, expand the Tool catalog (optional) panel (shown only under the Responses API protocol) and paste your OpenAI tools array as JSON. The same editor is available afterward from the target's edit dialog.

Tool catalog
[
  {
    "type": "function",
    "name": "get_weather",
    "description": "Look up the current weather for a city.",
    "parameters": {
      "type": "object",
      "properties": { "city": { "type": "string" } },
      "required": ["city"]
    }
  },
  { "type": "web_search" }
]

The editor accepts both the flat Responses API tool shape and the Chat Completions nested function shape ({ "type": "function", "function": { ... } }), normalizing the latter to flat. Switch to the Preview tab to see the parsed tools as a table. Invalid JSON blocks saving until you fix it. Declaring tools never affects the connection test.

Declaring is optional but recommended. Declared tools are available to Spectral from the first turn, and their JSON Schema parameters let Spectral check whether your agent's arguments are well-formed even when the agent does not advertise its catalog at runtime. This feeds the validity dimension of tool evaluation.

Tool discovery​

You don't have to declare anything. Spectral also discovers the tools your agent actually uses at evaluation time: it reads the tool catalog from the top-level tools field on each response (the flat Responses API tool shape) and from any mcp_list_tools items in the output array. A declared tool takes precedence over a discovered one with the same identity.

Streaming​

Streaming is not supported. Return the complete response in a single non-streamed reply.

Selecting the protocol​

When you create an API target, choose Chat Completions or Responses API. If you leave the default, Spectral probes your endpoint and detects the protocol for you before running the connection test. The protocol is fixed once the target is created.

Evaluating tool use​

When your agent calls tools, Spectral evaluates each call: whether it was a valid, well-chosen call with justified arguments, whether the result was useful, and whether the agent's answer faithfully used it.

Tool EvaluationHow Spectral scores tool calls, and where to read the results.