> ## 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 Schema > Create a new schema definition ## Schema Builder Tool To simplify the process of creating schemas, Flora offers a user-friendly Schema Builder tool. This visual interface allows you to construct your schema graphically, ensuring all requirements are met without the need to write JSON manually. You can access the Schema Builder at [https://withflora.io/schema-builder](https://withflora.io/schema-builder). Using the Schema Builder: 1. Navigate to the Schema Builder tool 2. Use the intuitive interface to add fields and define data types 3. Preview your schema structure in real-time 4. Once satisfied, you can directly create the schema via the API or copy the JSON for use in your API requests The Schema Builder is especially helpful for those new to JSON schema creation or for quickly prototyping complex data structures. ## OpenAPI ````yaml POST /schemas 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: /schemas: post: tags: - Schemas summary: create description: create operationId: create requestBody: content: application/json: schema: type: object properties: name: type: string example: News Articles structure: type: object examples: create: value: '' responses: '200': description: '200' headers: Connection: schema: type: string example: keep-alive Date: schema: type: string example: Thu, 20 Mar 2025 15:37:16 GMT Keep-Alive: schema: type: string example: timeout=5 content-length: schema: type: string example: '432' x-request-id: schema: type: string example: jemoclju67iz8kc25rnt1w5j content: application/json: schema: type: object properties: data: type: object properties: createdAt: type: string example: '2025-03-20T15:37:16.163+00:00' id: type: string example: 00f9190e-9a4a-4e08-ba00-f888437ed3c4 name: type: string example: News Articles structure: type: object properties: items: type: object properties: properties: type: object properties: link: type: object properties: describe: type: string example: URL to learn more type: type: string example: string summary: type: object properties: describe: type: string example: The news summary type: type: string example: string title: type: object properties: describe: type: string example: The article title type: type: string example: string type: type: string example: object required: type: boolean example: true type: type: string example: array message: type: string example: Schema created successfully status: type: boolean example: true examples: '200': value: data: createdAt: '2025-03-20T15:37:16.163+00:00' id: 00f9190e-9a4a-4e08-ba00-f888437ed3c4 name: News Articles structure: items: properties: link: describe: URL to learn more type: string summary: describe: The news summary type: string title: describe: The article title type: string type: object required: true type: array message: Schema created successfully status: true '422': description: '422' headers: Connection: schema: type: string example: keep-alive Date: schema: type: string example: Thu, 20 Mar 2025 15:37:41 GMT Keep-Alive: schema: type: string example: timeout=5 content-length: schema: type: string example: '181' x-request-id: schema: type: string example: tlz0c1twaqi8gp1p82a20grr content: application/json: schema: type: object properties: errors: type: array items: type: object properties: field: type: string example: name message: type: string example: The schema name is required example: - field: name message: The schema name is required - field: structure message: The schema structure is required message: type: string example: Validation failed status: type: boolean example: false examples: '422': value: errors: - field: name message: The schema name is required - field: structure message: The schema structure is required 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.