Direct answer

Send a Bearer API key to POST /agent/query with a JSON body containing query and an optional result limit. SPYN3 resolves the workspace from the key, searches only that workspace and returns an answer with supporting source records. Use /agent/search when you need ranked passages without synthesis.

Make the first query

Ask a cited questioncURL
curl "$SPYN3_API_URL/agent/query" \
  -H "Authorization: Bearer $SPYN3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Which contracts renew this quarter?",
    "limit": 5,
    "options": {
      "response_format": "json",
      "snippet_chars": 240
    }
  }'

The request does not contain a workspace ID. SPYN3 binds every machine credential to one workspace and resolves that boundary before retrieval. The exact hosted origin and secret are issued inside the beta dashboard.

Current agent endpoints

POST/agent/queryGenerate an answer and return the source records that support it.
POST/agent/searchReturn ranked source snippets without answer synthesis.
GET/agent/sourcesList connectors available to the authenticated workspace.
GET/agent/toolsInspect the tool names, descriptions and required permissions exposed by the gateway.
GET/agent/mcp/configReturn a ready-to-adapt MCP client configuration for the same credential.

Search and query accept connector_id or source_type filters. The result limit is bounded between 1 and 100. Query text is limited to 2,000 characters in the current beta contract.

Choose a response for the consumer

Agent endpoints default to TOON, a compact text representation for repetitive records. Set options.response_format to json when an application needs ordinary JSON. The response also carries an X-SPYN3-Usage header with aggregate result and estimated response-token information when usage hints are enabled.

Minimal by default

Search returns identifiers, bounded snippets and source metadata rather than whole documents.

Detail on demand

The MCP get_document tool retrieves bounded chunks after a relevant document is selected.

Format at the boundary

Choose compact agent text or application-friendly JSON without rebuilding retrieval.

Provenance invariant

Source records remain attached to search and answer flows; response policy cannot switch them off.

Read how SPYN3 structures cited, token-efficient responses before designing a client that blindly loads full documents.

Operational rules worth coding for

  • Treat 401 as an invalid, revoked or unsupported credential—not as permission to retry with broader credentials.
  • Treat 403 as a missing permission and request the smallest additional scope needed.
  • Honor rate-limit and usage responses; exponential retry does not create additional quota.
  • Log request identifiers and status, never the Bearer secret or retrieved customer content.
  • Use stable document identifiers for follow-up retrieval rather than repeating broad searches.

Private-beta boundary

This is the implemented agent gateway contract as of 13 September 2026. It is published so beta builders can evaluate the shape before onboarding. The service origin, availability commitments and final versioning policy are not yet generally available.

Your next client should reuse the same data work

Build against one governed endpoint

Connect the source once, ask one real question over REST, and keep the application logic in your hands. The same workspace can later serve an MCP client without a second ingestion pipeline.

Request private beta access
About SPYN3

SPYN3 is AI-ready data infrastructure for technical builders. It connects business sources into a workspace-isolated knowledge layer and exposes that layer through REST and a hosted MCP server, with permission-scoped access and cited retrieval. SPYN3 is currently in private beta.

Implementation basis

  1. Endpoints, request constraints and response controls were verified against the current SPYN3 private-beta gateway implementation on 13 Sep 2026.