> ## Documentation Index
> Fetch the complete documentation index at: https://docs.deasylabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List

> List all taxonomies (schemas/hierarchies) for the authenticated user.

## Request Body

| Field          | Type                  | Description                                                          |
|----------------|-----------------------|----------------------------------------------------------------------|
| `taxonomy_ids` | `Optional[List[str]]` | List of specific taxonomy IDs to retrieve. If omitted, returns all taxonomies. |

## Response

- **200**: Taxonomies retrieved successfully  
    - Returns: `{ "taxonomies": List[DeasyTaxonomy] }`
- **500**: Internal Server Error

## Example

```json
{
  "taxonomy_ids": ["document-categories", "sentiment-types"]
}
```



## OpenAPI

````yaml /deasy-openapi-stainless.yml post /taxonomy/list
openapi: 3.1.0
info:
  title: FastAPI
  version: 0.1.0
servers:
  - url: /rest/unstructured
security: []
paths:
  /taxonomy/list:
    post:
      tags:
        - Taxonomies
      summary: List
      description: >-
        List all taxonomies (schemas/hierarchies) for the authenticated user.


        ## Request Body


        | Field          | Type                  |
        Description                                                          |

        |----------------|-----------------------|----------------------------------------------------------------------|

        | `taxonomy_ids` | `Optional[List[str]]` | List of specific taxonomy IDs
        to retrieve. If omitted, returns all taxonomies. |


        ## Response


        - **200**: Taxonomies retrieved successfully  
            - Returns: `{ "taxonomies": List[DeasyTaxonomy] }`
        - **500**: Internal Server Error


        ## Example


        ```json

        {
          "taxonomy_ids": ["document-categories", "sentiment-types"]
        }

        ```
      operationId: list_taxonomies_route_taxonomy_list_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListTaxonomiesRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListTaxonomiesResponse'
        '403':
          description: Missing token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
        '500':
          description: >-
            Internal Server Error. An unexpected error occurred while processing
            the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
      security:
        - BasicAuth: []
        - BearerAuth: []
          UserIdAuth: []
      x-codeSamples:
        - lang: Python
          source: |-
            import os
            from unstructured import UnstructuredClient

            client = UnstructuredClient(
                username=os.environ.get("UNSTRUCTURED_USERNAME"),  # This is the default and can be omitted
                password=os.environ.get("UNSTRUCTURED_PASSWORD"),  # This is the default and can be omitted
            )
            taxonomies = client.taxonomy.list()
            print(taxonomies.taxonomies)
        - lang: JavaScript
          source: |-
            import UnstructuredClient from 'unstructured-sdk';

            const client = new UnstructuredClient({
              authMethod: 'My Auth Method',
              username: process.env['UNSTRUCTURED_USERNAME'], // This is the default and can be omitted
              password: process.env['UNSTRUCTURED_PASSWORD'], // This is the default and can be omitted
            });

            const taxonomies = await client.taxonomy.list();

            console.log(taxonomies.taxonomies);
components:
  schemas:
    ListTaxonomiesRequest:
      properties:
        taxonomy_ids:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Taxonomy Ids
      type: object
      title: ListTaxonomiesRequest
    ListTaxonomiesResponse:
      properties:
        taxonomies:
          items:
            $ref: '#/components/schemas/DeasyTaxonomy-Output'
          type: array
          title: Taxonomies
      type: object
      required:
        - taxonomies
      title: ListTaxonomiesResponse
    HTTPError:
      properties:
        detail:
          type: string
          title: Detail
      type: object
      required:
        - detail
      title: HTTPError
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    DeasyTaxonomy-Output:
      properties:
        taxonomy_id:
          type: string
          title: Taxonomy Id
        taxonomy_name:
          type: string
          title: Taxonomy Name
        taxonomy_description:
          type: string
          title: Taxonomy Description
        taxonomy_data:
          $ref: '#/components/schemas/TaxonomyGraph-Output'
        user_id:
          type: string
          title: User Id
        created_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Created At
        updated_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Updated At
        refreshed_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Refreshed At
      type: object
      required:
        - taxonomy_id
        - taxonomy_name
        - taxonomy_description
        - taxonomy_data
        - user_id
      title: DeasyTaxonomy
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    TaxonomyGraph-Output:
      properties:
        nodes:
          items:
            $ref: '#/components/schemas/TaxonomyNode'
          type: array
          title: Nodes
        edges:
          items:
            $ref: '#/components/schemas/TaxonomyEdge'
          type: array
          title: Edges
        root_node_id:
          type: string
          title: Root Node Id
          description: ID of the root node
          default: root
      type: object
      title: TaxonomyGraph
      description: |-
        A node/edge style graph representation of a taxonomy.

        Example (simple case - single condition per edge):
            graph = TaxonomyGraph(
                nodes=[
                    TaxonomyNode(node_id="1", name="Document Type", active_values=["Contract", "Invoice"]),
                    TaxonomyNode(node_id="2", name="Contract Type", active_values=["NDA", "Employment"]),
                ],
                edges=[
                    TaxonomyEdge(
                        target_node_ids=["1"],
                        conditions=[EdgeCondition(node_id="root", tag_value_name="Contract")],
                    ),
                    TaxonomyEdge(
                        target_node_ids=["2"],
                        conditions=[EdgeCondition(node_id="1", tag_value_name="NDA")],
                    ),
                ]
            )

        Example (AND case - multiple conditions):
            # Edge only followed when Document Type = Contract AND Region = US
            TaxonomyEdge(
                target_node_ids=["us_contract_node"],
                conditions=[
                    EdgeCondition(node_id="doc_type_node", tag_value_name="Contract"),
                    EdgeCondition(node_id="region_node", tag_value_name="US"),
                ],
            )
    TaxonomyNode:
      properties:
        node_id:
          type: string
          title: Node Id
        node_type:
          $ref: '#/components/schemas/TaxonomyNodeType'
          default: tag
        name:
          type: string
          title: Name
          description: The tag name
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
          description: >-
            Description of what this tag represents. Short and specific,
            capturing the relevant context.
        active_values:
          items:
            type: string
          type: array
          title: Active Values
          description: >-
            Allowed values for this tag. Empty list means all values from the
            tag definition are allowed.
      type: object
      required:
        - name
      title: TaxonomyNode
      description: >-
        A node in the taxonomy graph representing a tag.


        Nodes are tags with their metadata. The graph structure is defined

        by edges that connect parent nodes to child nodes with optional
        conditions.
    TaxonomyEdge:
      properties:
        edge_id:
          type: string
          title: Edge Id
        target_node_ids:
          items:
            type: string
          type: array
          title: Target Node Ids
          description: IDs of the child nodes
        conditions:
          items:
            $ref: '#/components/schemas/EdgeCondition'
          type: array
          title: Conditions
          description: >-
            Conditions that must ALL be true for this edge to be followed (AND
            logic)
      type: object
      required:
        - target_node_ids
        - conditions
      title: TaxonomyEdge
      description: >-
        An edge in the taxonomy graph connecting to child tags based on one or
        more conditions.


        For simple cases, use a single condition in the list.

        For AND cases, use multiple conditions - all must be satisfied.
    TaxonomyNodeType:
      type: string
      enum:
        - root
        - tag
      title: TaxonomyNodeType
      description: Types of nodes in a taxonomy graph
    EdgeCondition:
      properties:
        node_id:
          type: string
          title: Node Id
          description: ID of the node whose value must match
        tag_value_name:
          type: string
          title: Tag Value Name
          description: The tag value that must match
      type: object
      required:
        - node_id
        - tag_value_name
      title: EdgeCondition
      description: A single condition that must be met for an edge to be followed.
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
    BearerAuth:
      type: http
      scheme: bearer
    UserIdAuth:
      type: apiKey
      in: header
      name: X-User-ID

````