--- title: "Extract metadata (structured)" method: POST path: "/ai/extract_structured" tags: ["AI"] --- # Extract metadata (structured) `POST /ai/extract_structured` Sends an AI request to supported Large Language Models (LLMs) and returns extracted metadata as a set of key-value pairs. To define the extraction structure, provide either a metadata template or a list of fields. To learn more about creating templates, see [Creating metadata templates in the Admin Console](https://support.box.com/hc/en-us/articles/360044194033-Customizing-Metadata-Templates) or use the [metadata template API](https://developer.box.com/guides/metadata/templates/create). This endpoint also supports [Enhanced Extract Agent](https://developer.box.com/guides/box-ai/ai-tutorials/extract-metadata-structured#enhanced-extract-agent). For information about supported file formats and languages, see the [Extract metadata from file (structured)](https://developer.box.com/guides/box-ai/ai-tutorials/extract-metadata-structured) API guide. ## Request body - AiExtractStructured — AI Extract Structured Request object. - `items` AiItemBase[], required — The items to be processed by the LLM. Currently you can use files only. - `id` string, required — The ID of the file. - `type` 'file', required — The type of the item. Currently the value can be `file` only. - `content` string — The content of the item, often the text representation. - `metadata_template` object — The metadata template containing the fields to extract. For your request to work, you must provide either `metadata_template` or `fields`, but not both. - `template_key` string — The name of the metadata template. - `type` 'metadata_template' — Value is always `metadata_template`. - `scope` string — The scope of the metadata template that can either be global or enterprise. * The **global** scope is used for templates that are available to any Box enterprise. * The **enterprise** scope represents templates created within a specific enterprise, containing the ID of that enterprise. - `fields` object[] — The fields to be extracted from the provided items. For your request to work, you must provide either `metadata_template` or `fields`, but not both. - `key` string, required — A unique identifier for the field. - `description` string — A description of the field. - `displayName` string — The display name of the field. - `prompt` string — The context about the key that may include how to find and format it. - `type` string — The type of the field. It can include but is not limited to `string`, `float`, `date`, `enum`, `multiSelect`,`taxonomy`, `struct`, and `table`. - `options` object[] — A list of options for this field. This is most often used in combination with the `enum` and `multiSelect` field types. - `key` string, required — A unique identifier for the option. - `fields` AiExtractSubField[] — The nested fields for this field. Used with `struct` and `table` field types to define the nested structure. - `key` string, required — A unique identifier for the nested field. - `description` string — A description of the nested field. - `displayName` string — The display name of the nested field. - `prompt` string — Context about the nested field that may include how to find and how to format it. - `type` string — The type of the nested field. Allowed types include `string`, `float`, `date`, `number`, `text`, `boolean`, `enum` and `multiSelect`. - `options` AiExtractFieldOption[] — A list of options for this nested field. Used with `enum` and `multiSelect` types. - `key` string, required — A unique identifier for the option. - `taxonomy_key` string — The identifier for a taxonomy, which corresponds to the `key` of the taxonomy source. Required if using `taxonomy` type field. - `namespace` string — The namespace of the taxonomy source. Required if using `taxonomy` type field from an existing taxonomy. - `options_rules` AiOptionsRules — An object for a `taxonomy` type template field containing configuration for taxonomy options. Required if using `taxonomy` type field. - `multi_select` boolean — Indicates whether the field is a multi-select field. If true, the field can have multiple values. - `selectable_levels` integer[] — The selectable levels for the field. This is used to limit the levels of the taxonomy that can be selected. - `ai_agent` union - object — The AI agent to be used for the structured extraction. Defaults to the Standard Agent if not specified. If you want to use Enhanced Extract Agent, see [Enhanced Extract Agent](https://developer.box.com/guides/box-ai/ai-tutorials/extract-metadata-structured#enhanced-extract-agent) for details. - `type` 'ai_agent_id', required — The type of AI agent used to handle queries. - `id` string, required — The ID of an Agent. This can be a numeric ID for custom agents (for example, `14031`) or a unique identifier for pre-built agents (for example, `enhanced_extract_agent` for the [Enhanced Extract Agent](https://developer.box.com/guides/box-ai/ai-tutorials/extract-metadata-structured#enhanced-extract-agent)). - object — The AI agent to be used for the structured extraction. Defaults to the Standard Agent if not specified. If you want to use Enhanced Extract Agent, see [Enhanced Extract Agent](https://developer.box.com/guides/box-ai/ai-tutorials/extract-metadata-structured#enhanced-extract-agent) for details. - `type` 'ai_agent_extract_structured', required — The type of AI agent to be used for extraction. - `long_text` AiAgentLongTextTool — AI agent processor used to handle basic text. - `model` string — The model used for the AI agent for basic text. For specific model values, see the [available models list](https://developer.box.com/guides/box-ai/ai-models). - `num_tokens_for_completion` integer — The number of tokens for completion. - `llm_endpoint_params` union — The parameters for the LLM endpoint specific to a model. - object — AI LLM endpoint params OpenAI object. - `type` 'openai_params', required — The type of the AI LLM endpoint params object for OpenAI. This parameter is **required**. - `temperature` number, nullable — What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or `top_p` but not both. - `top_p` number, nullable — An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with `top_p` probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. We generally recommend altering this or temperature but not both. - `frequency_penalty` number, nullable — A number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim. - `presence_penalty` number, nullable — A number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics. - `stop` string, nullable — Up to 4 sequences where the API will stop generating further tokens. - object — AI LLM endpoint params Google object. - `type` 'google_params', required — The type of the AI LLM endpoint params object for Google. This parameter is **required**. - `temperature` number, nullable — The temperature is used for sampling during response generation, which occurs when `top-P` and `top-K` are applied. Temperature controls the degree of randomness in the token selection. - `top_p` number, nullable — `Top-P` changes how the model selects tokens for output. Tokens are selected from the most (see `top-K`) to least probable until the sum of their probabilities equals the `top-P` value. - `top_k` number, nullable — `Top-K` changes how the model selects tokens for output. A low `top-K` means the next selected token is the most probable among all tokens in the model's vocabulary (also called greedy decoding), while a high `top-K` means that the next token is selected from among the three most probable tokens by using temperature. - object — AI LLM endpoint params AWS object. - `type` 'aws_params', required — The type of the AI LLM endpoint params object for AWS. This parameter is **required**. - `temperature` number, nullable — What sampling temperature to use, between 0 and 1. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or `top_p` but not both. - `top_p` number, nullable — An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with `top_p` probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. We generally recommend altering this or temperature but not both. - object — AI LLM endpoint params IBM object. - `type` 'ibm_params', required — The type of the AI LLM endpoint params object for IBM. This parameter is **required**. - `temperature` number, nullable — What sampling temperature to use, between 0 and 1. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or `top_p` but not both. - `top_p` number, nullable — An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with `top_p` probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. We generally recommend altering this or temperature but not both. - `top_k` number, nullable — `Top-K` changes how the model selects tokens for output. A low `top-K` means the next selected token is the most probable among all tokens in the model's vocabulary (also called greedy decoding), while a high `top-K` means that the next token is selected from among the three most probable tokens by using temperature. - `system_message` string — System messages try to help the LLM "understand" its role and what it is supposed to do. - `prompt_template` string — The prompt template contains contextual information of the request and the user prompt. When passing `prompt_template` parameters, you **must include** inputs for `{user_question}` and `{content}`. `{current_date}` is optional, depending on the use. - `embeddings` object - `model` string — The model used for the AI agent for calculating embeddings. - `strategy` object - `id` string — The strategy used for the AI agent for calculating embeddings. - `num_tokens_per_chunk` integer — The number of tokens per chunk. - `basic_text` AiAgentBasicTextTool — AI agent processor used to handle basic text. - `model` string — The model used for the AI agent for basic text. For specific model values, see the [available models list](https://developer.box.com/guides/box-ai/ai-models). - `num_tokens_for_completion` integer — The number of tokens for completion. - `llm_endpoint_params` union — The parameters for the LLM endpoint specific to a model. - object — AI LLM endpoint params OpenAI object. - `type` 'openai_params', required — The type of the AI LLM endpoint params object for OpenAI. This parameter is **required**. - `temperature` number, nullable — What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or `top_p` but not both. - `top_p` number, nullable — An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with `top_p` probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. We generally recommend altering this or temperature but not both. - `frequency_penalty` number, nullable — A number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim. - `presence_penalty` number, nullable — A number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics. - `stop` string, nullable — Up to 4 sequences where the API will stop generating further tokens. - object — AI LLM endpoint params Google object. - `type` 'google_params', required — The type of the AI LLM endpoint params object for Google. This parameter is **required**. - `temperature` number, nullable — The temperature is used for sampling during response generation, which occurs when `top-P` and `top-K` are applied. Temperature controls the degree of randomness in the token selection. - `top_p` number, nullable — `Top-P` changes how the model selects tokens for output. Tokens are selected from the most (see `top-K`) to least probable until the sum of their probabilities equals the `top-P` value. - `top_k` number, nullable — `Top-K` changes how the model selects tokens for output. A low `top-K` means the next selected token is the most probable among all tokens in the model's vocabulary (also called greedy decoding), while a high `top-K` means that the next token is selected from among the three most probable tokens by using temperature. - object — AI LLM endpoint params AWS object. - `type` 'aws_params', required — The type of the AI LLM endpoint params object for AWS. This parameter is **required**. - `temperature` number, nullable — What sampling temperature to use, between 0 and 1. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or `top_p` but not both. - `top_p` number, nullable — An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with `top_p` probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. We generally recommend altering this or temperature but not both. - object — AI LLM endpoint params IBM object. - `type` 'ibm_params', required — The type of the AI LLM endpoint params object for IBM. This parameter is **required**. - `temperature` number, nullable — What sampling temperature to use, between 0 and 1. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or `top_p` but not both. - `top_p` number, nullable — An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with `top_p` probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. We generally recommend altering this or temperature but not both. - `top_k` number, nullable — `Top-K` changes how the model selects tokens for output. A low `top-K` means the next selected token is the most probable among all tokens in the model's vocabulary (also called greedy decoding), while a high `top-K` means that the next token is selected from among the three most probable tokens by using temperature. - `system_message` string — System messages try to help the LLM "understand" its role and what it is supposed to do. - `prompt_template` string — The prompt template contains contextual information of the request and the user prompt. When passing `prompt_template` parameters, you **must include** inputs for `{user_question}` and `{content}`. `{current_date}` is optional, depending on the use. - `basic_image` AiAgentBasicTextTool — AI agent processor used to handle basic text. - `model` string — The model used for the AI agent for basic text. For specific model values, see the [available models list](https://developer.box.com/guides/box-ai/ai-models). - `num_tokens_for_completion` integer — The number of tokens for completion. - `llm_endpoint_params` union — The parameters for the LLM endpoint specific to a model. - object — AI LLM endpoint params OpenAI object. - `type` 'openai_params', required — The type of the AI LLM endpoint params object for OpenAI. This parameter is **required**. - `temperature` number, nullable — What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or `top_p` but not both. - `top_p` number, nullable — An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with `top_p` probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. We generally recommend altering this or temperature but not both. - `frequency_penalty` number, nullable — A number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim. - `presence_penalty` number, nullable — A number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics. - `stop` string, nullable — Up to 4 sequences where the API will stop generating further tokens. - object — AI LLM endpoint params Google object. - `type` 'google_params', required — The type of the AI LLM endpoint params object for Google. This parameter is **required**. - `temperature` number, nullable — The temperature is used for sampling during response generation, which occurs when `top-P` and `top-K` are applied. Temperature controls the degree of randomness in the token selection. - `top_p` number, nullable — `Top-P` changes how the model selects tokens for output. Tokens are selected from the most (see `top-K`) to least probable until the sum of their probabilities equals the `top-P` value. - `top_k` number, nullable — `Top-K` changes how the model selects tokens for output. A low `top-K` means the next selected token is the most probable among all tokens in the model's vocabulary (also called greedy decoding), while a high `top-K` means that the next token is selected from among the three most probable tokens by using temperature. - object — AI LLM endpoint params AWS object. - `type` 'aws_params', required — The type of the AI LLM endpoint params object for AWS. This parameter is **required**. - `temperature` number, nullable — What sampling temperature to use, between 0 and 1. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or `top_p` but not both. - `top_p` number, nullable — An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with `top_p` probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. We generally recommend altering this or temperature but not both. - object — AI LLM endpoint params IBM object. - `type` 'ibm_params', required — The type of the AI LLM endpoint params object for IBM. This parameter is **required**. - `temperature` number, nullable — What sampling temperature to use, between 0 and 1. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or `top_p` but not both. - `top_p` number, nullable — An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with `top_p` probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. We generally recommend altering this or temperature but not both. - `top_k` number, nullable — `Top-K` changes how the model selects tokens for output. A low `top-K` means the next selected token is the most probable among all tokens in the model's vocabulary (also called greedy decoding), while a high `top-K` means that the next token is selected from among the three most probable tokens by using temperature. - `system_message` string — System messages try to help the LLM "understand" its role and what it is supposed to do. - `prompt_template` string — The prompt template contains contextual information of the request and the user prompt. When passing `prompt_template` parameters, you **must include** inputs for `{user_question}` and `{content}`. `{current_date}` is optional, depending on the use. - `include_confidence_score` boolean — A flag to indicate whether confidence scores for every extracted field should be returned. - `include_reference` boolean — A flag to indicate whether references for every extracted field should be returned. - `taxonomy_sources` AiTaxonomySource[] — The taxonomy sources to be used for the structured extraction. They can either be an existing file or a taxonomy. For your request to work, `fields` must also be provided. `taxonomy_sources` is not supported with `metadata_template`. - union — A taxonomy source to be used for the structured extraction. It can either be an existing CSV file or a taxonomy. - object — A taxonomy source to be used for the structured extraction. For your request to work, `fields` must also be provided. - `type` 'taxonomy' — The type of the taxonomy source. - `taxonomy_key` string — The identifier for a taxonomy, which corresponds to the `taxonomy_key` of the taxonomy source. - `namespace` string — The namespace of the taxonomy source. - object — A taxonomy `.csv` file to be used for the structured extraction. For your request to work, `fields` must also be provided. - `type` 'file' — The type of the taxonomy source. - `taxonomy_key` string — The identifier for a taxonomy, which corresponds to the `taxonomy_key` of the taxonomy source. - `id` string — The ID of the taxonomy source. Required if the type is `file` and unsupported if the type is `taxonomy`. ## Response `200` A successful response including the answer from the LLM. - AiExtractStructuredResponse — AI extract structured response. - `answer` AiExtractResponse, required — AI extract response. The content of this response may vary depending on the requested configuration. - `created_at` string, date-time, required — The ISO date formatted timestamp of when the answer to the prompt was created. - `completion_reason` string — The reason the response finishes. - `confidence_score` object — The confidence score levels and numeric values for each extracted field as a JSON dictionary. This can be empty if no field could be extracted. - `reference` object — The reference for each extracted field as a JSON dictionary. This can be empty if no field could be extracted. - `ai_agent_info` AiAgentInfo — The information on the models and processors used in the request. - `models` object[] — The models used for the request. - `name` string — The name of the model used for the request. - `provider` string — The provider that owns the model used for the request. - `supported_purpose` string — The supported purpose utilized by the model used for the request. - `processor` string — The processor used for the request. ## Other responses - `500` — An unexpected server error. - `default` — An unexpected error. --- [API](https://skmtc.net/box/apis/platform-api.md) · [All operations](https://skmtc.net/box/apis/platform-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/box/platform-api/revisions/ba8f087e1a4d/schema)