RecoupGet a free auditFree audit

API REFERENCE

Enrich

On this page
POST/api/research/enrich

Enrich an entity with structured data from web research. Provide a description of who or what to research and a JSON schema defining the fields to extract. Returns typed data with citations. Important: The schema object must include "type": "object" at the top level — requests without an explicit type will be rejected.

Authentication

See the authentication guide for API key and account access requirements.

Request

cURL
curl --request POST \
  --url 'https://api.recoupable.dev/api/research/enrich' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "input": "string",
  "schema": {
    "type": "object",
    "properties": {}
  }
}'

Try it

Fill in the fields, send the request from your browser, and read the live response. The curl below updates as you type.

Kept in this browser tab only and cleared when it closes.

cURL for this request
curl --request POST \
  --url 'https://recoup-api.vercel.app/api/research/enrich' \
  --header 'Content-Type: application/json' \
  --data '{
  "input": "string",
  "schema": {
    "type": "object",
    "properties": {}
  }
}'

Request body required

application/json

inputstringrequired

What to research (e.g., "Drake rapper from Dallas Texas").

schemaobjectrequired

JSON schema defining the fields to extract. Must include "type": "object" at the top level.

Properties for schema
typestring · enumrequired

Must be "object"

Values: "object"

propertiesobjectrequired

Field definitions to extract

Additional properties

Additional keys are allowed.

processorstring · enum

Research depth: base (fast), core (balanced), ultra (comprehensive).

Values: "base", "core", "ultra"

Default: "base"

Responses

200Structured enrichment data

application/json

statusstring
outputobject

Structured data matching the provided schema.

citationsarray<object>

Source citations supporting the enriched output.

Item properties for citations
urlstring

format: uri

titlestring
fieldstring

Which output field this citation supports.

400Validation error

application/json

statusstring · enumrequired

Values: "error"

errorstringrequired

Human-readable error message describing what went wrong.

401Authentication failed — invalid or missing API key

application/json

statusstring · enumrequired

Values: "error"

errorstringrequired

Human-readable error message describing what went wrong.

501The configured research data source does not support this endpoint or data shape.

application/json

statusstring · enumrequired

Values: "error"

errorstringrequired

Human-readable error message describing what went wrong.

501 example
{
  "status": "error",
  "error": "Request failed with status 501"
}

Full specification

Download the OpenAPI file for complete schemas, constraints, and examples.

Download research.json
View operation source
json
{
  "description": "Enrich an entity with structured data from web research. Provide a description of who or what to research and a JSON schema defining the fields to extract. Returns typed data with citations. **Important:** The `schema` object must include `\"type\": \"object\"` at the top level — requests without an explicit type will be rejected.",
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ResearchEnrichRequest"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Structured enrichment data",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ResearchEnrichResponse"
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ResearchErrorResponse"
          }
        }
      }
    },
    "401": {
      "description": "Authentication failed — invalid or missing API key",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ResearchErrorResponse"
          }
        }
      }
    },
    "501": {
      "$ref": "#/components/responses/ResearchDataSourceUnsupported"
    }
  }
}