v1

latestOpenAPI 3.0.02026-08-04891301.4 MB

Upload a file

Creates a new file from base64-encoded content and returns the resulting file object, including a signed download URL. Use this endpoint to store images, documents, or other binary assets that can then be referenced by agents, teams, or users.

App scope is derived from the authenticated viewer's bearer token or publishable key. You may optionally associate the file with an organization, team, user, or agent by passing the corresponding ID. If no owner is specified and the viewer is a user, the file is automatically attributed to that user.

Returns 422 when the data field is not valid base64 or the changeset is invalid. Returns 403 when the request lacks the required app scope.

post/api/v1/files

Request body

agentstring

Agent ID (agi_...) to associate with this file. When provided, the file's organization is derived from the agent.

content_typestring required

MIME type of the file, e.g. "image/png" or "application/pdf".

datastring required

Base64-encoded binary content of the file to upload.

filenamestring required

Original filename including extension, e.g. "avatar.png".

orgstring

Organization ID (org_...) to associate with this file. Optional; defaults to the viewer's organization when omitted.

teamstring

Team ID (tem_...) that owns this file. Takes precedence over user when both are provided.

userstring

User ID (usr_...) that owns this file. Defaults to the authenticated user when neither user nor team is specified.

Example request

{
  "agent": "string",
  "content_type": "application/json",
  "data": "string",
  "filename": "string",
  "org": "string",
  "team": "string",
  "user": "string"
}

Response

Successful response

content_typestring

MIME type of the file, e.g. "image/png" or "application/pdf".

created_atstring date-time

When the file was uploaded (ISO 8601).

filenamestring

Original filename as provided at upload time.

idstring required

File ID (fil_...).

orgstring

ID of the organization that owns this file (org_...).

sandboxstring

ID of the sandbox this file is scoped to (sbx_...). null for files not associated with a sandbox.

sizeinteger

Size of the file in bytes.

updated_atstring date-time

When the file record was last modified (ISO 8601).

urlstring

Short-lived signed URL for downloading the file. null if a URL could not be generated.

Example response

{
  "content_type": "application/json",
  "created_at": "2024-01-01T00:00:00Z",
  "filename": "document.pdf",
  "id": "fil_0aBcDeFgHiJkLmNoPqRsTu",
  "image_source": {
    "file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
    "height": 600,
    "media": "med_0aBcDeFgHiJkLmNoPqRsTu",
    "mime_type": "application/json",
    "refresh_url": "https://example.com",
    "url": "https://example.com",
    "width": 800
  },
  "org": "org_0aBcDeFgHiJkLmNoPqRsTu",
  "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu",
  "size": 1024,
  "updated_at": "2024-01-01T00:00:00Z",
  "url": "https://example.com"
}