# Extract URL

Source: https://recoupable.dev/docs/api-reference/research/extract

Extract clean markdown content from one or more public URLs. Handles JavaScript-heavy pages and PDFs. Returns focused excerpts aligned to an objective, or full page content.

## POST /api/research/extract

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/extract": {
      "post": {
        "description": "Extract clean markdown content from one or more public URLs. Handles JavaScript-heavy pages and PDFs. Returns focused excerpts aligned to an objective, or full page content.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ResearchExtractRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Extracted content from URLs",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResearchExtractResponse"
                }
              }
            }
          },
          "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": {
      "ResearchExtractRequest": {
        "type": "object",
        "required": [
          "urls"
        ],
        "properties": {
          "urls": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uri"
            },
            "maxItems": 10,
            "description": "URLs to extract content from (max 10).",
            "minItems": 1
          },
          "objective": {
            "type": "string",
            "description": "What information to focus on (optional, max 3000 chars)."
          },
          "full_content": {
            "type": "boolean",
            "default": false,
            "description": "Return full page content instead of focused excerpts."
          }
        }
      },
      "ResearchExtractResponse": {
        "type": "object",
        "required": [
          "status",
          "results"
        ],
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "success",
              "error"
            ],
            "example": "success"
          },
          "results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ResearchExtractResult"
            }
          },
          "errors": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "URLs that failed to extract. Only present when one or more URLs could not be processed."
          }
        }
      },
      "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"
          }
        }
      },
      "ResearchExtractResult": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "format": "uri"
          },
          "title": {
            "type": "string",
            "nullable": true
          },
          "publish_date": {
            "type": "string",
            "nullable": true,
            "description": "Publish date in YYYY-MM-DD format."
          },
          "excerpts": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "nullable": true,
            "description": "Focused excerpts as markdown."
          },
          "full_content": {
            "type": "string",
            "nullable": true,
            "description": "Full page content as markdown."
          }
        }
      }
    },
    "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"
            }
          }
        }
      }
    }
  }
}
```