---
title: "Register a logical namespace for a provider object"
method: POST
path: "/api/assets/mappings"
tags: ["Assets"]
---

# Register a logical namespace for a provider object

`POST /api/assets/mappings`

Idempotently maps a provider tuple to a logical swarm key without moving, renaming, reading, or writing the remote object.

## Request body

- object
  - `providerId` string, required
  - `orgId` string
  - `driveId` string
  - `providerKey` string, required
  - `key` string — Non-unique asset directory namespace (for example shared/ or personal/<user-id>/drafts/). Runtime write boundaries normalize and validate the canonical form.

## Response `200`

Mapping registered

- AssetKeyMapping
  - `id` string, required
  - `providerId` string, required
  - `providerOrgId` string
  - `providerDriveId` string
  - `providerKey` string, required
  - `key` string, required — Non-unique asset directory namespace (for example shared/ or personal/<user-id>/drafts/). Runtime write boundaries normalize and validate the canonical form.
  - `sourceEntityType` 'task-attachment' | 'external'
  - `sourceEntityId` string
  - `createdAt` string, date-time, required
  - `updatedAt` string, date-time, required
  - `createdBy` string
  - `updatedBy` string

## Other responses

- `400` — Invalid provider tuple or namespace
- `403` — Operator access required or personal namespace not authorized

---

[API](https://skmtc.net/desplega-ai/apis/agent-swarm-api.md) · [All operations](https://skmtc.net/desplega-ai/apis/agent-swarm-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/desplega-ai/agent-swarm-api/versions/ef761849166b/schema)