Structured outputs

Choose a caller-defined JSON Schema or the fixed, validator-owned stage-lookalike contract.

POST /v1/agent has two mutually exclusive machine-readable modes:

Use output_schema for a caller-defined result on an ordinary ask turn.
Use output_contract: "stage_aligned_lookalikes_v1" with stage_seed for stage- and scale-aligned company lookalikes.

The fixed stage contract returns the validator's result directly. It does not ask a second model turn to reshape, summarize, or reclassify the companies.

Stage-aligned lookalikes

Use SSE because evidence-backed stage research can run for several minutes.

curl -N https://api.ploid.com/v1/agent \
  -H "Authorization: Bearer $PLOID_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "operation": "ask",
    "prompt": "Research the seed and return evidence-backed companies at the same or an adjacent funding stage and comparable scale. Return zero rather than padding the result.",
    "stage_seed": {
      "canonical_name": "Ploy",
      "domain": "ploy.ai",
      "research_as_of_date": "2026-08-14"
    },
    "stage_options": {
      "requested_count": 10
    },
    "output_contract": "stage_aligned_lookalikes_v1",
    "sources": ["public_web"],
    "memory": "none",
    "response_format": "standard"
  }'

stage_seed and output_contract are a required pair on POST /v1/agent. A stage seed cannot be combined with output_schema. The legacy /v1/agent/chat route can use a stage seed as a conversational hint, but it does not provide this fixed machine contract.

stage_options.requested_count accepts 1 through 25 and defaults to 10. It is bound to the immutable specialist maxRetained value and reconciled against companyMatches.requestedCount. A shortfall is valid; the service never pads the result to reach this maximum.

Read the fixed result

In an SSE response, consume the single data-structured-output event. The display sample below is intentionally abridged; generate types from the full OpenAPI schema.

{
  "type": "data-structured-output",
  "data": {
    "structured_output": {
      "schema_version": "stage_aligned_lookalikes_v1",
      "decision_authority": "deterministic_validator",
      "result": {
        "answer": "...",
        "sources": [],
        "caveats": [],
        "companyMatches": {
          "researchAsOfDate": "2026-08-14",
          "seed": {
            "canonicalName": "Ploy",
            "domain": "ploy.ai"
          },
          "requestedCount": 10,
          "retainedCount": 0,
          "retained": [],
          "eligibleOverflow": [],
          "analogues": [],
          "rejected": []
        }
      }
    }
  }
}

With Accept: application/json, the same object is returned at data.structured_output (also abridged below):

{
  "data": {
    "output": "",
    "artifacts": [],
    "structured_output": {
      "schema_version": "stage_aligned_lookalikes_v1",
      "decision_authority": "deterministic_validator",
      "result": {
        "answer": "...",
        "sources": [],
        "caveats": [],
        "companyMatches": {
          "researchAsOfDate": "2026-08-14",
          "seed": {
            "canonicalName": "Ploy",
            "domain": "ploy.ai"
          },
          "requestedCount": 10,
          "retainedCount": 0,
          "retained": [],
          "eligibleOverflow": [],
          "analogues": [],
          "rejected": []
        }
      }
    }
  },
  "meta": {
    "output_contract": "stage_aligned_lookalikes_v1"
  }
}

Zero retained candidates is a successful, valid result. If validator provenance, seed binding, or the classification lifecycle cannot be verified, the API emits an explicit error and does not substitute prose.

The complete SalesBricks launch boundary and ownership model is recorded in the SalesBricks Agent API integration guide.

Caller-defined schemas

For non-stage tasks, add output_schema when downstream code needs its own fields:

{
  "operation": "ask",
  "prompt": "Research Retool and return its canonical identity with source URLs.",
  "response_format": "standard",
  "output_schema": {
    "type": "object",
    "properties": {
      "company": { "type": "string" },
      "domain": { "type": "string" },
      "source_urls": {
        "type": "array",
        "items": { "type": "string", "format": "uri" }
      }
    },
    "required": ["company", "domain", "source_urls"],
    "additionalProperties": false
  }
}

The validated value is returned at data.structured_output, or in the SSE event of the same name.

Contract rules

output_schema and output_contract cannot be combined.
stage_seed requires output_contract: "stage_aligned_lookalikes_v1", and that contract requires stage_seed.
The fixed stage contract requires the explicit source and memory policy shown above: sources: ["public_web"] and memory: "none".
Fixed stage-contract jobs must omit session_id; each job starts a fresh isolated session.
stage_options.requested_count is optional, bounded to 1–25, and defaults to 10.
Both modes are available only for operation: "ask" with response_format: "standard".
A caller schema must contain at least one JSON Schema type or constraint and can be at most 16,000 UTF-8 bytes.
Caller schemas are not retained for later turns, even when session_id is reused.
Validate schema_version before consuming a server-owned fixed contract.

Fail closed

Never treat text as a successful substitute for a requested structured result. Retry or surface the explicit API error.

Structured outputs

Stage-aligned lookalikes

Read the fixed result

Caller-defined schemas

Contract rules

On this page