> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.athenaintel.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.athenaintel.com/_mcp/server. # Invoke POST https://api.athenaintel.com/api/v0/tools/structured-data-extractor/invoke Content-Type: application/json Extract structured data. tl;dr: * pass a valid JSON schema in `json_schema` * pass the page chunks as a list of `Chunk` objects, by default: `{"type": "text", "content": "..."}` * leave all other fields as default Detailed configuration (only relevant for complex use cases): The structured data extractor's architecture follows the map-reduce pattern, where the asset is divided into chunks, the schema is extracted from each chunk, and the chunks are then reduced to a single structured data object. In some applications, you may not want to: * map (if your input asset is small enough) * reduce (if your output object is large enough that it will overflow the output length; if you're extracting a long list of entities; if youre ) to extract all instances of the schema). You can configure these behaviors with the `map` and `reduce` fields. Reference: https://docs.athenaintel.com/api-reference/tools/structured-data-extractor/invoke ## Authentication - `X-API-KEY` header (required) — API Key authentication via header ## Request ### Body (application/json) This endpoint expects a StructuredDataExtractorRequest. - `chunks` (list of Chunk, required) — The chunks from which to extract structured data. - `json_schema` (map from string to any, required) — The JSON schema to use for validation (version draft 2020-12). See the docs [here](https://json-schema.org/learn/getting-started-step-by-step). - `chunk_messages` (list of PromptMessage, optional, default: [{"content":"\nYou are a data extraction specialist.\n","type":"system"},{"content":"\nPlease extract all matching information from the following text.\nFor each item, make sure you are 100% sure the the value is correct.\nIt must be unambugously clear from the document.\nOtherwise, don't extract that item and move on.\n\nKeep in mind that not all fields will be on all pages,\nand many pages will not contain any fields.\n","type":"human"}]) — The prompt to use for the data extraction over *each individual chunk*. It must be a list of messages. The chunk content will be appended as a list of human messages. - `reduce` (boolean, optional, default: true) — If `map`, whether to reduce the chunks to a single structured object (true) or return the full list (false). Use True unless you want to preserve duplicates from each page or expect the object to overflow the output context. - `reduce_messages` (list of PromptMessage, optional, default: [{"content":"You are a data specialist.","type":"system"},{"content":"Please review the following two extraction attempts and combine / merge / deduplicate them into a single correct result.","type":"human"}]) — The prompt to use for the reduce steps. It must be a list of messages. The two extraction attempts will be appended as a list of human messages. ## Response ### 200 Successful Response - `chunk_by_chunk_data` (list of ChunkResult, required, nullable) — The extracted structured data for each chunk. A list where each element is guaranteed to match `json_schema`. - `reduced_data` (map from string to any, required, nullable) — If reduce is True, the reduced structured data, otherwise null. Guaranteed to match `json_schema`. ## Errors ### 422 Unprocessable Entity Error Validation Error - `detail` (list of ValidationError, optional) ## Types ### Chunk A chunk of content to extract data from. - `chunk_id` (string, required) - `content` (list of ChunkContentItems, required) - `metadata` (map from string to string, optional, nullable) ### PromptMessage A message to use for the structured data extractor. - `content` (string, required) - `type` (enum, required) - Allowed values: `system`, `human`, `user` ### ChunkResult The result of a chunk extraction. - `chunk_id` (ChunkResultChunkId, required) - `chunk_result` (map from string to any, required, nullable) ### ValidationError - `loc` (list of ValidationErrorLocItems, required) - `msg` (string, required) - `type` (string, required) - `ctx` (ValidationErrorCtx, optional) - `input` (any, optional) ### ChunkContentItems - TextContent: TextContent - ImageUrlContent: ImageUrlContent ### ChunkResultChunkId - string - integer ### ValidationErrorLocItems - string - integer ### ValidationErrorCtx ### TextContent A text content item in a multimodal message content. - `text` (string, required) - `type` ("text", required) ### ImageUrlContent An image content item. - `image_url` (map from string to string, required) - `type` ("image_url", required) ## Examples **Request** ```json { "chunks": [ { "chunk_id": "1", "content": [ { "text": "John Smith is a 35 year old developer. You can reach him at john.smith@example.com", "type": "text" } ] }, { "chunk_id": "2", "content": [ { "text": "Jane Doe is a 25 year old developer. You can reach her at jane@example.com", "type": "text" } ] } ], "json_schema": { "description": "A person", "properties": { "age": { "type": "integer" }, "email": { "type": "string" }, "name": { "type": "string" } }, "required": [ "name" ], "title": "Person", "type": "object" } } ``` **Response** ```json { "chunk_by_chunk_data": [ { "chunk_id": "1", "chunk_result": { "age": 35, "email": "john.smith@example.com", "name": "John Smith" } }, { "chunk_id": "2", "chunk_result": { "age": 25, "email": "jane@example.com", "name": "Jane Doe" } } ], "reduced_data": { "age": 25, "email": "jane@example.com", "name": "Jane Doe" } } ``` **SDK Code** ```python import requests url = "https://api.athenaintel.com/api/v0/tools/structured-data-extractor/invoke" payload = { "chunks": [ { "chunk_id": "1", "content": [ { "text": "John Smith is a 35 year old developer. You can reach him at john.smith@example.com", "type": "text" } ] }, { "chunk_id": "2", "content": [ { "text": "Jane Doe is a 25 year old developer. You can reach her at jane@example.com", "type": "text" } ] } ], "json_schema": { "description": "A person", "properties": { "age": { "type": "integer" }, "email": { "type": "string" }, "name": { "type": "string" } }, "required": ["name"], "title": "Person", "type": "object" } } headers = { "X-API-KEY": "", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript const url = 'https://api.athenaintel.com/api/v0/tools/structured-data-extractor/invoke'; const options = { method: 'POST', headers: {'X-API-KEY': '', 'Content-Type': 'application/json'}, body: '{"chunks":[{"chunk_id":"1","content":[{"text":"John Smith is a 35 year old developer. You can reach him at john.smith@example.com","type":"text"}]},{"chunk_id":"2","content":[{"text":"Jane Doe is a 25 year old developer. You can reach her at jane@example.com","type":"text"}]}],"json_schema":{"description":"A person","properties":{"age":{"type":"integer"},"email":{"type":"string"},"name":{"type":"string"}},"required":["name"],"title":"Person","type":"object"}}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.athenaintel.com/api/v0/tools/structured-data-extractor/invoke" payload := strings.NewReader("{\n \"chunks\": [\n {\n \"chunk_id\": \"1\",\n \"content\": [\n {\n \"text\": \"John Smith is a 35 year old developer. You can reach him at john.smith@example.com\",\n \"type\": \"text\"\n }\n ]\n },\n {\n \"chunk_id\": \"2\",\n \"content\": [\n {\n \"text\": \"Jane Doe is a 25 year old developer. You can reach her at jane@example.com\",\n \"type\": \"text\"\n }\n ]\n }\n ],\n \"json_schema\": {\n \"description\": \"A person\",\n \"properties\": {\n \"age\": {\n \"type\": \"integer\"\n },\n \"email\": {\n \"type\": \"string\"\n },\n \"name\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"name\"\n ],\n \"title\": \"Person\",\n \"type\": \"object\"\n }\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("X-API-KEY", "") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.athenaintel.com/api/v0/tools/structured-data-extractor/invoke") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["X-API-KEY"] = '' request["Content-Type"] = 'application/json' request.body = "{\n \"chunks\": [\n {\n \"chunk_id\": \"1\",\n \"content\": [\n {\n \"text\": \"John Smith is a 35 year old developer. You can reach him at john.smith@example.com\",\n \"type\": \"text\"\n }\n ]\n },\n {\n \"chunk_id\": \"2\",\n \"content\": [\n {\n \"text\": \"Jane Doe is a 25 year old developer. You can reach her at jane@example.com\",\n \"type\": \"text\"\n }\n ]\n }\n ],\n \"json_schema\": {\n \"description\": \"A person\",\n \"properties\": {\n \"age\": {\n \"type\": \"integer\"\n },\n \"email\": {\n \"type\": \"string\"\n },\n \"name\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"name\"\n ],\n \"title\": \"Person\",\n \"type\": \"object\"\n }\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.athenaintel.com/api/v0/tools/structured-data-extractor/invoke") .header("X-API-KEY", "") .header("Content-Type", "application/json") .body("{\n \"chunks\": [\n {\n \"chunk_id\": \"1\",\n \"content\": [\n {\n \"text\": \"John Smith is a 35 year old developer. You can reach him at john.smith@example.com\",\n \"type\": \"text\"\n }\n ]\n },\n {\n \"chunk_id\": \"2\",\n \"content\": [\n {\n \"text\": \"Jane Doe is a 25 year old developer. You can reach her at jane@example.com\",\n \"type\": \"text\"\n }\n ]\n }\n ],\n \"json_schema\": {\n \"description\": \"A person\",\n \"properties\": {\n \"age\": {\n \"type\": \"integer\"\n },\n \"email\": {\n \"type\": \"string\"\n },\n \"name\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"name\"\n ],\n \"title\": \"Person\",\n \"type\": \"object\"\n }\n}") .asString(); ``` ```php request('POST', 'https://api.athenaintel.com/api/v0/tools/structured-data-extractor/invoke', [ 'body' => '{ "chunks": [ { "chunk_id": "1", "content": [ { "text": "John Smith is a 35 year old developer. You can reach him at john.smith@example.com", "type": "text" } ] }, { "chunk_id": "2", "content": [ { "text": "Jane Doe is a 25 year old developer. You can reach her at jane@example.com", "type": "text" } ] } ], "json_schema": { "description": "A person", "properties": { "age": { "type": "integer" }, "email": { "type": "string" }, "name": { "type": "string" } }, "required": [ "name" ], "title": "Person", "type": "object" } }', 'headers' => [ 'Content-Type' => 'application/json', 'X-API-KEY' => '', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.athenaintel.com/api/v0/tools/structured-data-extractor/invoke"); var request = new RestRequest(Method.POST); request.AddHeader("X-API-KEY", ""); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"chunks\": [\n {\n \"chunk_id\": \"1\",\n \"content\": [\n {\n \"text\": \"John Smith is a 35 year old developer. You can reach him at john.smith@example.com\",\n \"type\": \"text\"\n }\n ]\n },\n {\n \"chunk_id\": \"2\",\n \"content\": [\n {\n \"text\": \"Jane Doe is a 25 year old developer. You can reach her at jane@example.com\",\n \"type\": \"text\"\n }\n ]\n }\n ],\n \"json_schema\": {\n \"description\": \"A person\",\n \"properties\": {\n \"age\": {\n \"type\": \"integer\"\n },\n \"email\": {\n \"type\": \"string\"\n },\n \"name\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"name\"\n ],\n \"title\": \"Person\",\n \"type\": \"object\"\n }\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "X-API-KEY": "", "Content-Type": "application/json" ] let parameters = [ "chunks": [ [ "chunk_id": "1", "content": [ [ "text": "John Smith is a 35 year old developer. You can reach him at john.smith@example.com", "type": "text" ] ] ], [ "chunk_id": "2", "content": [ [ "text": "Jane Doe is a 25 year old developer. You can reach her at jane@example.com", "type": "text" ] ] ] ], "json_schema": [ "description": "A person", "properties": [ "age": ["type": "integer"], "email": ["type": "string"], "name": ["type": "string"] ], "required": ["name"], "title": "Person", "type": "object" ] ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.athenaintel.com/api/v0/tools/structured-data-extractor/invoke")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```