---
title: "POST /api/agent/v1/collection"
method: POST
path: "/api/agent/v1/collection"
tags: ["/api/agent"]
---

# POST /api/agent/v1/collection

`POST /api/agent/v1/collection`

## Request

- Base URL: `` (relative, and the document was published on a file host, not at the API’s origin)
- URL: `/api/agent/v1/collection`
- Auth: API key in header `X-API-Key`

Create a new Collection.

  Pass `parent_collection_id` to nest under another collection; omit for a root-level collection.
  The caller must have write access to the parent (or root, if no parent given).

## Request body

- MetabaseAgentApiApiCreateCollectionRequest: Request shape for `create_collection`. `:parent_collection_id` is named separately from the internal `:parent_id` field to make the LLM-facing API less ambiguous (the caller is saying "put it under this parent", not echoing back a server-set field).
  - `description` string, nullable
  - `name` string, required: value must be a non-blank string.
  - `parent_collection_id` integer, nullable: value must be an integer greater than zero.

## Response `2XX`

Successful response

- MetabaseAgentApiApiCreateCollectionResponse: Returned by `create_collection`. Exposes the materialized-path `:location` so callers can sanity-check nesting without a follow-up read.
  - `description` string, nullable, required
  - `id` integer, required: value must be an integer greater than zero.
  - `location` string, required: value must be a non-blank string.
  - `name` string, required: value must be a non-blank string.
  - `parent_id` integer, nullable, required: value must be an integer greater than zero.

## Other responses

- `4XX`: Client error response
- `5XX`: Server error response

## Changes

- **2026-11-04** `2e178f5a7934`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/metabase/apis/metabase-api/changes/api/agent/v1/collection/post.md)

---

[API](https://skmtc.dev/metabase/apis/metabase-api.md) - [All operations](https://skmtc.dev/metabase/apis/metabase-api/llms.txt) - [OpenAPI document](https://skmtc.dev/metabase/apis/metabase-api/revisions/2e178f5a7934?raw)