> ## Documentation Index > Fetch the complete documentation index at: https://docs.withflora.io/llms.txt > Use this file to discover all available pages before exploring further. # Create Extraction > Extract data from an unstructured source using a schema ## OpenAPI ````yaml POST /extractions openapi: 3.0.3 info: title: Flora API Documentation description: >- Flora is an AI-powered API for unstructured data. ## The Flora API Key API is required to access the Flora API you should pass the key via the request header in this format: `Authorization: Bearer {{FLORA_API_KEY}}` To get your Flora API key, sign in to [https://withflora.io/](https://withflora.io/) and head to the API key section. ## Requests and Responses Request body and response data are formatted as JSON. Response Content-Type will always be `application/json`. It is recommended to use HTTP status codes to determine the result of an API call, however, each request response contains a `status` property which is either `true` when the request was successful or `false` when the request fails. ## Response Format **Status Code:** **`200`** will have data response in this format. ``` typescript { "status": true, "message": "Success message", "data": {...}, } ``` Requests with paginated response data will have an additional property called `meta` which contains the pagination info. e.g. ``` typescript { "status": true, "message": "Operation successfully", "data": { "meta": { "total": 10, "perPage": 10, "currentPage": 1, "lastPage": 1, "firstPage": 1, "firstPageUrl": "/?page=1", "lastPageUrl": "/?page=1", "nextPageUrl": null, "previousPageUrl": null }, "data": [...] }, } ``` **Status Code:** **`422`** Is returned when there is a request body validation error, below is an example response data. ``` typescript { "status": false, "errors": [ { "field": "email", "message": "email is required to sign up" }, { "field": "password", "message": "password is required to sign up" }, ... ] } ``` **Status Code:** **`401`**, **`403`**, and **`500`** response data will contain a `status` and `message` property. The message property gives an overview of the error. ``` typescript { "status": false, "message": "Unauthorized access" } ``` ## Request Throttling **Status Code:** **`429`** response data will contain a `code` and `message` property. The message property gives an overview of the error. The request throttling is currently only applied to these endponts: \- ``` json { "status": false "message": "Maximum number of requests exceeded. Please try again later.", } ``` version: 1.0.0 contact: {} servers: - url: https://api.withflora.io/v1 security: - bearerAuth: [] tags: - name: Schemas description: >- The **Schema Endpoint** in **Flora's API** enables users to define structured data formats for extracting information from unstructured sources like images, PDFs, text, and webpages. This endpoint serves as the foundation for how extracted data is formatted and returned. #### **Key Functionalities:** - **Create a Schema:** Define a structured format, including required fields, data types, and validation rules. - **Retrieve Schemas:** Fetch existing schemas by ID or list all available schemas. - **Update a Schema:** Modify an existing schema to adapt to changing data needs. - **Delete a Schema:** Remove a schema that is no longer needed. #### **Usage Workflow:** 1. **Define a Schema:** Specify the fields and structure in JSON format. 2. **Use in Extraction Requests:** Pass the `schema_id` when sending data for processing. 3. **Receive Structured Output:** Flora extracts and returns data based on the defined schema. ### Guide to Creating a Valid Schema This guide will help you create a valid schema. Follow the steps below to ensure your schema meets the necessary requirements. #### 1\. **Schema Structure** Your schema must be a valid JSON object with a specific structure. The root object should have a `type` field, which can be either `array` or `object`. #### 2\. **Array Type Schema** If the `type` is `array`, the schema must include an `items` field that defines the structure of the array elements. - **Items Field**: The `items` field must be an object with a `type` field, which can be either `object` or `array`. - **Object Type Items**: If the `items.type` is `object`, it must include a `properties` field that defines the fields of the object. - **Array Type Items**: If the `items.type` is `array`, it must include an `items` field to define the nested array structure. Example: ``` json { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the item" }, "price": { "type": "number", "description": "The price of the item" } } } } ``` #### 3\. **Object Type Schema** If the `type` is `object`, the schema must include a `properties` field that defines the fields of the object. - **Properties Field**: The `properties` field must be an object where each key is a field name and the value is an object defining the field type and other attributes. Example: ``` json { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the item" }, "price": { "type": "number", "description": "The price of the item" } } } ``` #### 4\. **Required Fields** You can specify required fields using the `required` attribute. For arrays, the `required` attribute can be used within the `items` field to specify required properties of the array elements. Example: ``` json { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the item", "required": true }, "price": { "type": "number", "description": "The price of the item" } } } ``` - name: Extractions description: >- The **Extractions Endpoint** in **Flora's API** enables users to extract structured data from unstructured sources (images, PDFs, text, webpages) by supplying a **valid URL** and linking it to a predefined schema. #### **Key Functionalities:** - **Initiate an Extraction:** Submit a source URL along with a `schema_id` for processing. - **Retrieve Extracted Data:** Access structured data based on the provided schema. - **List All Extractions:** View a history of extractions and their statuses. - **Delete an Extraction:** Remove an extraction record when no longer needed. #### **Usage Workflow:** 1. **Define a Schema:** Use the `/schemas` endpoint to create a structured format. 2. **Submit an Extraction Request:** Provide: - `schema_id` (required) → ID of the schema to use. - `type` (required) → Input type (`image`, `pdf`, `text`, `webpage`). - `source` (required) → A **valid, accessible URL** pointing to the data. - `model` (optional) → Preferred AI model (`gpt-4.1`, `gpt-4.1-mini`). - `instruction` (optional) → Additional processing instructions. 3. **Receive Extracted Data:** The API processes the source and returns structured output based on the schema. 4. **Track Status (Optional):** Check request history and status if handling large volumes. **Authentication:** Requires a valid API key via `Authorization: Bearer {token}`. This endpoint provides **a seamless way to extract structured data from online sources**, automating workflows and eliminating manual data processing. paths: /extractions: post: tags: - Extractions summary: create description: create operationId: create1 requestBody: content: multipart/form-data: schema: type: object properties: schema_id: description: >- The schema ID. Create a schema first using the `POST /schemas` endpoint. type: string example: ec9cb821-6f69-4605-a7fc-0858667eb534 type: description: >- The input type can be any of `text`, `image`, `pdf`, and `webpage`. type: string example: image model: description: >- Optional. Can be either 'gpt-4o' or 'gpt-4o-mini', we will use 'gpt-4o' by default type: string enum: - gpt-4.1 - gpt-4.1-mini example: gpt-4.1 source: description: |- When type is: PDF - Pass a valid and accesible pdf url Image - Pass a valid and accesible image url Webpage - Pass a valid and accesible webpage url Text - Text content to extract data from type: string example: https://8ddf98.jpg responses: '200': description: 200 - Image / 200 - Webpage headers: Content-Length: schema: type: string example: '2456' Date: schema: type: string example: Sat, 22 Mar 2025 17:56:45 GMT Server: schema: type: string example: railway-edge X-Railway-Edge: schema: type: string example: railway/asia-southeast1-eqsg3a X-Railway-Request-Id: schema: type: string example: dkLnwONfQCKRViJIjiKt_Q_1774336823 X-Request-Id: schema: type: string example: wustgsi8rgb4i6f3e76cze5a content: application/json: schema: type: object properties: data: type: object properties: id: type: string example: c39c0c98-d71c-471c-a7e0-6e3fcf2f8298 output: anyOf: - type: object properties: amount: type: number example: 38580 currency: type: string example: NGN products: type: array items: type: object properties: amount: type: number example: 1600 name: type: string example: Jendol Chicken Pie quantity: type: number example: 2 example: - amount: 1600 name: Jendol Chicken Pie quantity: 2 - amount: 6200 name: Rose Carla Tissue quantity: 2 - amount: 7800 name: Ctn Lasena Table quantity: 2 - amount: 1700 name: Green & Red Apple quantity: 1 - amount: 2150 name: Roll Nescafe Break quantity: 1 - amount: 2340 name: Hollandia Evaporated Milk quantity: 3 - amount: 2840 name: Tesco Spaghetti 500g quantity: 2 - amount: 3750 name: Ayoola Poundo Yam quantity: 1 - amount: 5000 name: Seedless Grape quantity: 1 - amount: 1600 name: Jendol Loaf Bread quantity: 1 - amount: 3600 name: Greenco Large Brown Egg quantity: 1 storeName: type: string example: Jendol Superstores - type: array items: type: object properties: link: type: string example: >- https://techcabal.com/google-taara-lightbridge-starlink/ summary: type: string example: >- Google’s Taara team is advancing internet connectivity with its laser-powered technology, providing a competitive alternative to Elon Musk’s Starlink. The technology aims to deliver internet services in less accessible regions by utilizing laser beams to transfer data, thereby offering a solution where traditional infrastructure is challenging or expensive. title: type: string example: >- Google's Taara Lightbridge takes on Starlink with laser-powered internet example: - summary: >- Google’s Taara team is advancing internet connectivity with its laser-powered technology, providing a competitive alternative to Elon Musk’s Starlink. The technology aims to deliver internet services in less accessible regions by utilizing laser beams to transfer data, thereby offering a solution where traditional infrastructure is challenging or expensive. title: >- Google's Taara Lightbridge takes on Starlink with laser-powered internet - summary: >- Alitheia and Goodwell have achieved a successful exit from their investment in Baobab Nigeria, realizing a 3x return. The acquisition highlights a significant milestone in the fintech landscape of Nigeria, demonstrating substantial value creation and growth potential within the sector. title: >- Baobab Nigeria acquisition delivers 3x return for Alitheia and Goodwell - summary: >- In Kenya, Uber and Bolt continue to dominate the ride-hailing market despite the emergence of over 2,500 competing apps. The drivers' union outlines challenges these apps face, including inadequate funding, high competition, and the need for robust operational infrastructure to attract both drivers and customers. title: >- Over 2,500 ride-hailing apps have tried—and failed—to compete with Uber, Bolt – drivers’ union - summary: >- Mysten Labs’ co-founder has initiated a $1.3 million fund targeted at training African software engineers. This initiative underscores a commitment to enhancing technical skills across the continent, aiming to expand the talent pool and support the burgeoning tech ecosystem in Africa. title: >- Mysten Labs co-founder launches $1.3 million fund to train African software engineers totalTokens: type: number example: 1795 message: type: string example: Extraction completed successfully status: type: boolean example: true examples: 200 - Image: value: data: id: c39c0c98-d71c-471c-a7e0-6e3fcf2f8298 output: amount: 38580 currency: NGN products: - amount: 1600 name: Chicken Pie quantity: 2 - amount: 3750 name: Ayoola Poundo Yam quantity: 1 - amount: 5000 name: Seedless Grape quantity: 1 storeName: XYZ Superstores totalTokens: 1795 message: Extraction completed successfully status: true 200 - Webpage: value: data: id: 168c87d4-602f-424b-9015-5adb65532b00 output: - link: >- https://techcabal.com/google-taara-lightbridge-starlink/ summary: >- Google’s Taara team is advancing internet connectivity with its laser-powered technology, providing a competitive alternative to Elon Musk’s Starlink. The technology aims to deliver internet services in less accessible regions by utilizing laser beams to transfer data, thereby offering a solution where traditional infrastructure is challenging or expensive. title: >- Google's Taara Lightbridge takes on Starlink with laser-powered internet - link: >- https://techcabal.com/article/baobab-nigeria-acquisition/ summary: >- Alitheia and Goodwell have achieved a successful exit from their investment in Baobab Nigeria, realizing a 3x return. The acquisition highlights a significant milestone in the fintech landscape of Nigeria, demonstrating substantial value creation and growth potential within the sector. title: >- Baobab Nigeria acquisition delivers 3x return for Alitheia and Goodwell - link: >- https://techcabal.com/news/exclusive-kenya-ride-hailing-apps-fail summary: >- In Kenya, Uber and Bolt continue to dominate the ride-hailing market despite the emergence of over 2,500 competing apps. The drivers' union outlines challenges these apps face, including inadequate funding, high competition, and the need for robust operational infrastructure to attract both drivers and customers. title: >- Over 2,500 ride-hailing apps have tried—and failed—to compete with Uber, Bolt – drivers’ union - link: >- https://techcabal.com/newsletters/2025-techcabal-daily/ summary: >- The latest edition of TechCabal Daily covers key topics in African tech, including a feature on Valu’s market listing. This newsletter continues to provide valuable insights and updates on the tech landscape across Africa. title: TechCabal Daily – A Valu-ed listing - link: >- https://techcabal.com/acquisition/mysten-labs-fund-launch summary: >- Mysten Labs’ co-founder has initiated a $1.3 million fund targeted at training African software engineers. This initiative underscores a commitment to enhancing technical skills across the continent, aiming to expand the talent pool and support the burgeoning tech ecosystem in Africa. title: >- Mysten Labs co-founder launches $1.3 million fund to train African software engineers totalTokens: 30334 message: Extraction completed successfully status: true '422': description: '422' headers: Connection: schema: type: string example: keep-alive Date: schema: type: string example: Fri, 21 Mar 2025 10:05:12 GMT Keep-Alive: schema: type: string example: timeout=5 content-length: schema: type: string example: '232' x-request-id: schema: type: string example: cd7lhzu9npk3upbc13wlxi6o content: application/json: schema: type: object properties: errors: type: array items: type: object properties: field: type: string example: schema_id message: type: string example: The schema_id field must be defined example: - field: schema_id message: The schema_id field must be defined - field: type message: The type field must be defined - field: '' message: Invalid source data message: type: string example: Validation failed status: type: boolean example: false examples: '422': value: errors: - field: schema_id message: The schema_id field must be defined - field: type message: The type field must be defined - field: '' message: Invalid source data message: Validation failed status: false components: securitySchemes: bearerAuth: type: http scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.