# Enrich

Source: https://recoupable.dev/docs/api-reference/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.

## POST /api/research/enrich

Full OpenAPI specification: https://recoupable.dev/docs/spec/research.json

## Authentication

The supplied specification does not declare an OpenAPI security object for this operation. Its declared headers and parameters still apply. Consult the authentication guide and the full specification before calling it.

[Authentication guide](https://recoupable.dev/docs/authentication)

## Operation and referenced schemas

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Recoup API - Research",
    "description": "API documentation for the Recoup platform - an AI agent platform for the music industry",
    "license": {
      "name": "MIT"
    },
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://api.recoupable.dev"
    }
  ],
  "paths": {
    "/api/research/enrich": {
      "post": {
        "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"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ResearchEnrichRequest": {
        "type": "object",
        "required": [
          "input",
          "schema"
        ],
        "properties": {
          "input": {
            "type": "string",
            "description": "What to research (e.g., \"Drake rapper from Dallas Texas\")."
          },
          "schema": {
            "type": "object",
            "description": "JSON schema defining the fields to extract. Must include `\"type\": \"object\"` at the top level.",
            "additionalProperties": true,
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "object"
                ],
                "description": "Must be \"object\""
              },
              "properties": {
                "type": "object",
                "description": "Field definitions to extract",
                "additionalProperties": true
              }
            },
            "required": [
              "type",
              "properties"
            ]
          },
          "processor": {
            "type": "string",
            "enum": [
              "base",
              "core",
              "ultra"
            ],
            "default": "base",
            "description": "Research depth: base (fast), core (balanced), ultra (comprehensive)."
          }
        }
      },
      "ResearchEnrichResponse": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "example": "success"
          },
          "output": {
            "type": "object",
            "description": "Structured data matching the provided schema.",
            "additionalProperties": true
          },
          "citations": {
            "type": "array",
            "description": "Source citations supporting the enriched output.",
            "items": {
              "type": "object",
              "properties": {
                "url": {
                  "type": "string",
                  "format": "uri"
                },
                "title": {
                  "type": "string"
                },
                "field": {
                  "type": "string",
                  "description": "Which output field this citation supports."
                }
              }
            }
          }
        }
      },
      "ResearchErrorResponse": {
        "type": "object",
        "required": [
          "status",
          "error"
        ],
        "description": "Error response returned by all research endpoints for validation failures (400) and authentication errors (401).",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "error"
            ],
            "example": "error"
          },
          "error": {
            "type": "string",
            "description": "Human-readable error message describing what went wrong.",
            "example": "Missing required parameter: artist"
          }
        }
      }
    },
    "responses": {
      "ResearchDataSourceUnsupported": {
        "description": "The configured research data source does not support this endpoint or data shape.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ResearchErrorResponse"
            },
            "example": {
              "status": "error",
              "error": "Request failed with status 501"
            }
          }
        }
      }
    }
  }
}
```