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

# Introduction

> Programmatically manage second-party taxonomies

A second-party taxonomy provides a mapping of segment codes to human-readable names and metadata (e.g. descriptions) for use in building Permutive cohorts.

The Taxonomy API allows for the programmatic creation, mutation, and deletion of second-party taxonomies for imported data in your workspace.

## Authentication

It's important to note that all requests to the Taxonomy API must be authenticated with a private API key. See the [Authentication](/api/authentication) documentation for details on obtaining and using a private API key.

## Endpoints

The Taxonomy API provides 11 endpoints:

<CardGroup cols={3}>
  <Card title="Get all imports" icon="tag" href="./get-imports">
    Get all imports for a workspace.
  </Card>

  <Card title="Retrieve an import" icon="tag" href="./get-import">
    Retrieve a specific import by its import ID.
  </Card>

  <Card title="Get all segments for an import" icon="tag" href="./get-segments-for-import">
    Get all segments for a given import.
  </Card>

  <Card title="Get a segment by its ID" icon="tag" href="./get-a-segment-by-id">
    Get a segments for an import by its public import ID.
  </Card>

  <Card title="Get a segment by its code" icon="tag" href="./get-a-segment-by-code">
    Get a segment for an import by its code.
  </Card>

  <Card title="Create a segment" icon="tag" href="./create-a-segment">
    Create a segment for an import.
  </Card>

  <Card title="Update a segment by its public ID" icon="tag" href="./update-a-segment-by-id">
    Update a segment for an import by its public import ID.
  </Card>

  <Card title="Update a segment by its code" icon="tag" href="./update-a-segment-by-code">
    Update a segment for an import by its code.
  </Card>

  <Card title="Batch update segments" icon="tag" href="./batch-update">
    Batch update segments for an import.
  </Card>

  <Card title="Delete a segment by its public ID" icon="tag" href="./delete-a-segment-by-id">
    Delete a segment for an import by its public import ID.
  </Card>

  <Card title="Delete a segment by its code" icon="tag" href="./delete-a-segment-by-code">
    Delete a segment for an import by its code.
  </Card>
</CardGroup>