Files

File uploads are asynchronous; poll file status before starting report workflows when needed.

Schemas are generated from the API contract. Examples and guide links are maintained to stay aligned with the live API. Do not hand-edit this page.

`POST /v1/files`

Upload media via multipart form-data.

Usage notes

Request body is multipart form-data with file and optional label fields.
Upload acceptance does not mean the media is ready for report generation yet.

Request example

curl -X POST https://api.mappa.ai/v1/files \
  -H "Mappa-Api-Key: $CONDUIT_API_KEY" \
  -F "file=@./candidate-call.mp3" \
  -F "label=candidate-call"

Response example

{
  "mediaId": "media_abc123",
  "label": "candidate-call",
  "contentType": "audio/mpeg",
  "source": "MANUAL_UPLOAD",
  "createdAt": "2026-03-23T12:00:00.000Z",
  "createdByApiKeyId": "key_abc123",
  "createdByUserId": "user_abc123",
  "workspaceId": "ws_abc123"
}

Common errors

415 unsupported_media_type - The uploaded file type is not supported for ingestion on this surface.
401 - The API key is missing or invalid for the target workspace.

Direct API workflow - Upload -> create job -> complete async work with current REST examples.
Error codes - HTTP statuses, billing failures, and removed-surface migration notes.

Response schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "contentType": {
      "type": "string"
    },
    "createdByApiKeyId": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "createdByUserId": {
      "type": "string"
    },
    "createdAt": {
      "type": "string"
    },
    "durationSeconds": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ]
    },
    "label": {
      "type": "string"
    },
    "mediaId": {
      "type": "string"
    },
    "source": {
      "type": "string",
      "enum": [
        "NOTETAKER",
        "MANUAL_UPLOAD",
        "PLAYGROUND",
        "SDK"
      ]
    },
    "sizeBytes": {
      "anyOf": [
        {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991
        },
        {
          "type": "null"
        }
      ]
    },
    "workspaceId": {
      "type": "string"
    }
  },
  "required": [
    "contentType",
    "createdByApiKeyId",
    "createdByUserId",
    "createdAt",
    "label",
    "mediaId",
    "source",
    "workspaceId"
  ],
  "additionalProperties": false
}

`GET /v1/files`

List workspace media files.

Usage notes

Use cursor pagination for incremental backfills or operator tooling.
Use GET /v1/files/:mediaId when you need current processing state for one upload.

Request example

curl "https://api.mappa.ai/v1/files?limit=10&search=candidate" \
  -H "Mappa-Api-Key: $CONDUIT_API_KEY"

Response example

{
  "files": [
    {
      "mediaId": "media_abc123",
      "label": "candidate-call",
      "processingStatus": "COMPLETED",
      "hasReports": true,
      "contentType": "audio/mpeg",
      "createdAt": "2026-03-23T12:00:00.000Z",
      "lastUsedAt": "2026-03-23T12:05:00.000Z",
      "retention": {
        "locked": false,
        "daysRemaining": 180,
        "expiresAt": "2026-09-19T12:00:00.000Z"
      },
      "source": "MANUAL_UPLOAD",
      "createdByApiKeyId": "key_abc123",
      "createdByUserId": "user_abc123",
      "workspaceId": "ws_abc123"
    }
  ],
  "hasMore": false,
  "nextCursor": null
}

Common errors

400 - The requested cursor is invalid or no longer usable.

Direct API workflow - Upload -> create job -> complete async work with current REST examples.

Query schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "createdAfter": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
    },
    "createdByUserId": {
      "type": "string"
    },
    "cursor": {
      "type": "string"
    },
    "includeDeleted": {
      "default": false,
      "type": "boolean"
    },
    "limit": {
      "default": 20,
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "search": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    }
  },
  "required": [
    "includeDeleted",
    "limit"
  ],
  "additionalProperties": false
}

Response schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "files": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "contentType": {
            "type": "string"
          },
          "createdByApiKeyId": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "createdByUserId": {
            "type": "string"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
          },
          "durationSeconds": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ]
          },
          "hasReports": {
            "type": "boolean"
          },
          "label": {
            "type": "string"
          },
          "lastUsedAt": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
              },
              {
                "type": "null"
              }
            ]
          },
          "mediaId": {
            "type": "string"
          },
          "processingStatus": {
            "type": "string",
            "enum": [
              "PENDING",
              "PROCESSING",
              "COMPLETED",
              "FAILED"
            ]
          },
          "retention": {
            "type": "object",
            "properties": {
              "daysRemaining": {
                "anyOf": [
                  {
                    "type": "integer",
                    "minimum": -9007199254740991,
                    "maximum": 9007199254740991
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "Days until expiry (null if locked or deleted)"
              },
              "expiresAt": {
                "anyOf": [
                  {
                    "type": "string",
                    "format": "date-time",
                    "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "When the file will expire (null if locked)"
              },
              "locked": {
                "type": "boolean",
                "description": "Whether the file is locked from automatic deletion"
              }
            },
            "required": [
              "daysRemaining",
              "expiresAt",
              "locked"
            ],
            "additionalProperties": false
          },
          "source": {
            "type": "string",
            "enum": [
              "NOTETAKER",
              "MANUAL_UPLOAD",
              "PLAYGROUND",
              "SDK"
            ]
          },
          "sizeBytes": {
            "anyOf": [
              {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              {
                "type": "null"
              }
            ]
          },
          "workspaceId": {
            "type": "string"
          }
        },
        "required": [
          "contentType",
          "createdByApiKeyId",
          "createdByUserId",
          "createdAt",
          "hasReports",
          "label",
          "lastUsedAt",
          "mediaId",
          "processingStatus",
          "retention",
          "source",
          "workspaceId"
        ],
        "additionalProperties": false
      }
    },
    "hasMore": {
      "type": "boolean"
    },
    "nextCursor": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "files",
    "hasMore",
    "nextCursor"
  ],
  "additionalProperties": false
}

`GET /v1/files/:mediaId`

Fetch one media file by id.

Usage notes

Wait for processingStatus to become COMPLETED before creating a report job.
If processingStatus becomes FAILED, inspect the source media before retrying.

Request example

curl https://api.mappa.ai/v1/files/media_abc123 \
  -H "Mappa-Api-Key: $CONDUIT_API_KEY"

Response example

{
  "mediaId": "media_abc123",
  "label": "candidate-call",
  "processingStatus": "COMPLETED",
  "hasReports": false,
  "contentType": "audio/mpeg",
  "createdAt": "2026-03-23T12:00:00.000Z",
  "lastUsedAt": null,
  "retention": {
    "locked": false,
    "daysRemaining": 180,
    "expiresAt": "2026-09-19T12:00:00.000Z"
  },
  "source": "MANUAL_UPLOAD",
  "createdByApiKeyId": "key_abc123",
  "createdByUserId": "user_abc123",
  "workspaceId": "ws_abc123"
}

Common errors

404 not_found - The mediaId does not exist in the authenticated workspace.

Direct API workflow - Upload -> create job -> complete async work with current REST examples.
Error codes - HTTP statuses, billing failures, and removed-surface migration notes.

Response schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "contentType": {
      "type": "string"
    },
    "createdByApiKeyId": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "createdByUserId": {
      "type": "string"
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
    },
    "durationSeconds": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ]
    },
    "hasReports": {
      "type": "boolean"
    },
    "label": {
      "type": "string"
    },
    "lastUsedAt": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
        },
        {
          "type": "null"
        }
      ]
    },
    "mediaId": {
      "type": "string"
    },
    "processingStatus": {
      "type": "string",
      "enum": [
        "PENDING",
        "PROCESSING",
        "COMPLETED",
        "FAILED"
      ]
    },
    "retention": {
      "type": "object",
      "properties": {
        "daysRemaining": {
          "anyOf": [
            {
              "type": "integer",
              "minimum": -9007199254740991,
              "maximum": 9007199254740991
            },
            {
              "type": "null"
            }
          ],
          "description": "Days until expiry (null if locked or deleted)"
        },
        "expiresAt": {
          "anyOf": [
            {
              "type": "string",
              "format": "date-time",
              "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
            },
            {
              "type": "null"
            }
          ],
          "description": "When the file will expire (null if locked)"
        },
        "locked": {
          "type": "boolean",
          "description": "Whether the file is locked from automatic deletion"
        }
      },
      "required": [
        "daysRemaining",
        "expiresAt",
        "locked"
      ],
      "additionalProperties": false
    },
    "source": {
      "type": "string",
      "enum": [
        "NOTETAKER",
        "MANUAL_UPLOAD",
        "PLAYGROUND",
        "SDK"
      ]
    },
    "sizeBytes": {
      "anyOf": [
        {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991
        },
        {
          "type": "null"
        }
      ]
    },
    "workspaceId": {
      "type": "string"
    }
  },
  "required": [
    "contentType",
    "createdByApiKeyId",
    "createdByUserId",
    "createdAt",
    "hasReports",
    "label",
    "lastUsedAt",
    "mediaId",
    "processingStatus",
    "retention",
    "source",
    "workspaceId"
  ],
  "additionalProperties": false
}

`GET /v1/files/:mediaId/speakers`

List the diarized speakers detected in one media file, with each speaker's transcript.

Usage notes

speakers is empty until status becomes ready; poll while it is processing.
transcript is everything that speaker said across the recording, joined into one string.
Use speakerIndex here as the target.speaker_index value when creating a report job.

Request example

curl https://api.mappa.ai/v1/files/media_abc123/speakers \
  -H "Mappa-Api-Key: $CONDUIT_API_KEY"

Response example

{
  "mediaId": "media_abc123",
  "status": "ready",
  "durationSeconds": 412.5,
  "speakers": [
    {
      "speakerIndex": 0,
      "speechSeconds": 240.1,
      "transcript": "Hi, thanks for jumping on the call today. I wanted to walk through where we landed on the rollout…"
    },
    {
      "speakerIndex": 1,
      "speechSeconds": 172.4,
      "transcript": "Sure, happy to walk you through the pricing and the rollout plan…"
    }
  ]
}

Common errors

404 not_found - The mediaId does not exist in the authenticated workspace.
410 gone - The media file was deleted and is no longer available.

Direct API workflow - Upload -> create job -> complete async work with current REST examples.
Error codes - HTTP statuses, billing failures, and removed-surface migration notes.

Response schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "durationSeconds": {
      "anyOf": [
        {
          "type": "number",
          "minimum": 0
        },
        {
          "type": "null"
        }
      ]
    },
    "mediaId": {
      "type": "string",
      "minLength": 1
    },
    "speakers": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "speechSeconds": {
            "type": "number",
            "minimum": 0
          },
          "speakerIndex": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          },
          "transcript": {
            "type": "string"
          }
        },
        "required": [
          "speechSeconds",
          "speakerIndex",
          "transcript"
        ],
        "additionalProperties": false
      }
    },
    "status": {
      "type": "string",
      "enum": [
        "processing",
        "ready",
        "failed"
      ]
    }
  },
  "required": [
    "durationSeconds",
    "mediaId",
    "speakers",
    "status"
  ],
  "additionalProperties": false
}

`PATCH /v1/files/:mediaId/retention`

Lock or unlock automatic retention deletion.

Request example

curl -X PATCH https://api.mappa.ai/v1/files/media_abc123/retention \
  -H "Mappa-Api-Key: $CONDUIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "lock": true
  }'

Response example

{
  "mediaId": "media_abc123",
  "message": "Retention lock updated",
  "retentionLock": true
}

Common errors

422 - The lock field is missing or not a boolean value.

Error codes - HTTP statuses, billing failures, and removed-surface migration notes.

Request schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "lock": {
      "type": "boolean",
      "description": "Set to true to lock, false to unlock"
    }
  },
  "required": [
    "lock"
  ],
  "additionalProperties": false
}

Response schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "mediaId": {
      "type": "string"
    },
    "message": {
      "type": "string"
    },
    "retentionLock": {
      "type": "boolean"
    }
  },
  "required": [
    "mediaId",
    "message",
    "retentionLock"
  ],
  "additionalProperties": false
}

`DELETE /v1/files/:mediaId`

Delete media file metadata and storage.

Request example

curl -X DELETE https://api.mappa.ai/v1/files/media_abc123 \
  -H "Mappa-Api-Key: $CONDUIT_API_KEY"

Response example

{
  "deleted": true,
  "mediaId": "media_abc123"
}

Common errors

404 not_found - The mediaId does not exist or is already deleted.

Error codes - HTTP statuses, billing failures, and removed-surface migration notes.

Response schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "deleted": {
      "type": "boolean",
      "const": true
    },
    "mediaId": {
      "type": "string"
    }
  },
  "required": [
    "deleted",
    "mediaId"
  ],
  "additionalProperties": false
}

POST /v1/files​

Usage notes​

Request example​

Response example​

Common errors​

Related guides​

Response schema​

GET /v1/files​

Usage notes​

Request example​

Response example​

Common errors​

Related guides​

Query schema​

Response schema​

GET /v1/files/:mediaId​

Usage notes​

Request example​

Response example​

Common errors​

Related guides​

Response schema​

GET /v1/files/:mediaId/speakers​

Usage notes​

Request example​

Response example​

Common errors​

Related guides​

Response schema​

PATCH /v1/files/:mediaId/retention​

Request example​

Response example​

Common errors​

Related guides​

Request schema​

Response schema​

DELETE /v1/files/:mediaId​

Request example​

Response example​

Common errors​

Related guides​

Response schema​

`POST /v1/files`

Usage notes

Request example

Response example

Common errors

Related guides

Response schema

`GET /v1/files`

Usage notes

Request example

Response example

Common errors

Related guides

Query schema

Response schema

`GET /v1/files/:mediaId`

Usage notes

Request example

Response example

Common errors

Related guides

Response schema

`GET /v1/files/:mediaId/speakers`

Usage notes

Request example

Response example

Common errors

Related guides

Response schema

`PATCH /v1/files/:mediaId/retention`

Request example

Response example

Common errors

Related guides

Request schema

Response schema

`DELETE /v1/files/:mediaId`

Request example

Response example

Common errors

Related guides

Response schema