Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
description: Agent-first API for runtime + developer control-plane operations (users, teams, agents, routines, context, workflows, integrations, and webhooks).
title: ArchAstro Platform Files API
version: v1
tags:
- name: Files
paths:
/api/v1/files:
post:
description: '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.
The JSON body uses Platform''s default 8,000,000-byte parser budget; the
an upstream proxy in front of Platform may have a separate 32 MiB request cap. Base64 requires
`4 * ceil(binary_bytes / 3)` bytes, plus the UTF-8 JSON envelope (including
filename, owner IDs, escaping and other fields). For an envelope of E bytes,
budget at most `3 * floor((8,000,000 - E) / 4)` binary bytes: less than
6,000,000 bytes (about 5.72 MiB). Do not rely on parser chunk overshoot.
Oversized JSON requests are rejected with HTTP 413 before upload processing.
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.
Pass `share: true` to additionally mint a stable public URL for the file
(returned as `share_url`), fetchable by anyone without authentication — for
example to embed an uploaded image in a GitHub PR body or other external
markdown. The URL does not expire. Sharing is revoked by setting
`share: false` on `PATCH /api/v1/files/:file` with the same credential
(or `archastro update file --unshare`); re-enabling sharing
reactivates previously issued URLs. Only image content types can be
shared.
Returns `422` when the `data` field is not valid base64, the changeset is
invalid, or `share` is requested for a non-image content type.
Returns `403` when the request lacks the required app scope.'
operationId: post_api_v1_files
parameters: []
requestBody:
content:
application/json:
schema:
example:
acl:
add:
- actions:
- read
- write
principal: string
principal_type: user
grants:
- actions:
- read
- write
principal: string
principal_type: user
remove:
- principal: string
principal_type: user
agent: string
content_type: application/json
data: string
filename: string
org: string
share: true
team: string
user: string
properties:
acl:
description: Access control list for the file. Supports explicit `read` and `write` grants to users, teams, organizations, organization roles, agents, or everyone.
example:
add:
- actions:
- read
- write
principal: string
principal_type: user
grants:
- actions:
- read
- write
principal: string
principal_type: user
remove:
- principal: string
principal_type: user
properties:
add:
description: 'Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.'
example:
- actions:
- read
- write
principal: string
principal_type: user
items:
description: A single access-control grant that pairs a principal with the set of actions it is allowed to perform.
example:
actions:
- read
- write
principal: string
principal_type: user
properties:
actions:
description: Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.
example:
- read
- write
items:
type: string
type: array
principal:
description: The identifier of the principal. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`; omit entirely when `principal_type` is `"everyone"`.
example: string
type: string
principal_type:
description: The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.
example: user
type: string
required:
- actions
- principal_type
type: object
type: array
grants:
description: 'Replace mode: the complete new list of grants that replaces all existing entries. Send an empty array (`[]`) to clear all grants. Cannot be combined with `add` or `remove`.'
example:
- actions:
- read
- write
principal: string
principal_type: user
items:
description: A single access-control grant that pairs a principal with the set of actions it is allowed to perform.
example:
actions:
- read
- write
principal: string
principal_type: user
properties:
actions:
description: Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.
example:
- read
- write
items:
type: string
type: array
principal:
description: The identifier of the principal. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`; omit entirely when `principal_type` is `"everyone"`.
example: string
type: string
principal_type:
description: The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.
example: user
type: string
required:
- actions
- principal_type
type: object
type: array
remove:
description: 'Patch mode: principals whose grants should be removed from the existing list. Cannot be combined with `grants`.'
example:
- principal: string
principal_type: user
items:
description: Identifies a principal to be removed from an access-control list.
example:
principal: string
principal_type: user
properties:
principal:
description: The identifier of the principal to remove. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`. Omit when `principal_type` is `"everyone"`.
example: string
type: string
principal_type:
description: The kind of principal to remove. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.
example: user
type: string
required:
- principal_type
type: object
type: array
type: object
agent:
description: Agent ID (`agi_...`) to associate with this file. When provided, the file's organization is derived from the agent.
example: string
type: string
content_type:
description: MIME type of the file, e.g. `"image/png"` or `"application/pdf"`.
example: application/json
type: string
data:
description: Base64-encoded binary content of the file to upload.
example: string
type: string
filename:
description: Original filename including extension, e.g. `"avatar.png"`.
example: string
type: string
org:
description: Organization ID (`org_...`) to associate with this file. Optional; defaults to the viewer's organization when omitted.
example: string
type: string
share:
description: When `true`, marks the file publicly shareable and returns a stable, non-expiring `share_url` fetchable without authentication. Only image content types can be shared.
example: true
type: boolean
team:
description: Team ID (`tem_...`) that owns this file. Takes precedence over `user` when both are provided.
example: string
type: string
user:
description: User ID (`usr_...`) that owns this file. Defaults to the authenticated user when neither `user` nor `team` is specified.
example: string
type: string
required:
- content_type
- data
- filename
type: object
required: true
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/StorageFile'
description: The newly created file, including a signed download URL.
'401':
description: Unauthorized
'403':
description: Forbidden - app scope required
'422':
description: Validation failed or invalid base64
summary: Upload a file
x-auth:
- bearer
- publishable_key
tags:
- Files
/api/v1/files/{file}:
patch:
description: 'Updates mutable fields of an existing file. Only the fields you supply are
changed; omitted fields retain their current values. The file''s stored content
and `content_type` cannot be changed after creation.
This endpoint is the companion to `share: true` on file upload: the same
credential that granted public sharing can revoke it here with `share: false`
(or grant it later with `share: true`; only image content types can be
shared, and re-enabling sharing reactivates any previously issued share
URLs). App scope is derived from the authenticated viewer, matching upload.
A file that exists but is not visible to the current viewer returns `404`
rather than `403` to avoid revealing the file''s existence.'
operationId: patch_api_v1_files__file
parameters:
- description: File ID (`fil_...`) of the file to update.
example: string
in: path
name: file
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
example:
filename: string
provider_metadata:
key: value
share: true
properties:
filename:
description: New name for the file, including extension, e.g. `"report_v2.pdf"`. Omit to leave the current filename unchanged.
example: string
type: string
provider_metadata:
description: Arbitrary key-value map of provider-specific metadata to store alongside the file. Replaces the entire existing `provider_metadata` map. Omit to leave it unchanged.
example:
key: value
type: object
share:
description: Set `true` to mark the file publicly shareable via its stable `share_url` (image content types only), or `false` to revoke public sharing. Re-enabling sharing reactivates any previously issued share URLs for the file. Omit to leave sharing unchanged.
example: true
type: boolean
type: object
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/StorageFile'
description: The updated file, including a signed download URL.
'401':
description: Unauthorized
'403':
description: Forbidden - app scope required
'404':
description: File not found
'422':
description: Validation failed
summary: Update a file
x-auth:
- bearer
- publishable_key
tags:
- Files
/api/v1/files/{file}/avatar:
get:
description: 'Returns the raw image bytes for an agent''s or user''s profile picture identified
by `file`. Chat messages and integration partners (such as Slack) fetch avatars
through it with plain GET requests, without bearer tokens. Authorization is
performed via a short, stable capability `token` rather than an HTTP header.
The `token` is an HMAC-based capability tied to the file ID. It does not expire,
but it is invalidated when the profile picture is replaced or its agent or user
is deleted — shared caches may continue serving the old image until the
`Cache-Control` max-age of one hour elapses. The endpoint never redirects to
a signed storage URL; bytes are served inline so behavior is consistent across
storage backends.
All failure modes — invalid file ID, invalid token, file not currently referenced
as an agent avatar — return a uniform `404` to avoid acting as an existence oracle.'
operationId: get_api_v1_files__file_avatar
parameters:
- description: File ID of the profile picture (`fil_...`). Must be currently set as an agent's or user's profile picture within the same app.
example: string
in: path
name: file
required: true
schema:
type: string
- description: HMAC capability token authorizing access to this specific file. Obtained from the avatar URL minted when the profile picture was set.
example: string
in: query
name: token
required: true
schema:
type: string
responses:
'200':
content:
'*/*':
schema:
format: binary
type: string
description: Raw image bytes of the avatar, served with the file's original content type.
'404':
description: Not found
summary: Fetch an agent or user avatar image
tags:
- Files
/api/v1/files/{file}/download:
get:
description: 'Returns the raw binary content of a file the authenticated viewer may see.
The response `Content-Type` header reflects the file''s stored MIME type and
`Content-Disposition` names the file as an attachment, so a browser can hand
the body to the download manager directly.
Unlike `Show` (which mints a storage URL the browser must resolve itself),
this endpoint serves bytes inline through the authenticated API mount, so it
behaves identically across storage backends: local files are not exposed as
unauthenticated static paths, and signed GCS URLs never cross the browser
boundary. A file that exists but is not visible to the current viewer
returns `404` rather than `403` to avoid revealing the file''s existence.
Byte downloads are limited to 32 MiB (33,554,432 bytes). The storage provider
enforces this limit on actual content, independently of stored size metadata.
Larger content returns HTTP `413` with error code `content_too_large`.'
operationId: get_api_v1_files__file_download
parameters:
- description: File ID (`fil_...`) of the file to download.
example: string
in: path
name: file
required: true
schema:
type: string
responses:
'200':
content:
'*/*':
schema:
format: binary
type: string
description: Raw binary content of the file, served with the file's stored MIME type.
'401':
description: Unauthorized
'403':
description: Forbidden - app scope required
'404':
description: File not found
'413':
description: File content exceeds the 32 MiB download limit
'502':
description: File content temporarily unavailable
summary: Download a file's bytes
x-auth:
- bearer
- publishable_key
tags:
- Files
/api/v1/files/{file}/org_logo:
get:
description: 'Returns the raw image bytes for an organization''s logo identified by `file`.
This endpoint backs the `org_logo.url` field of catalog payloads (such as
`GET /api/v1/solutions`), which anonymous consumers — the public marketplace''s
page cache, OpenGraph scrapers — may hold far longer than a signed storage URL
lives. Authorization is performed via a short, stable capability `token` rather
than an HTTP header, so the URL never expires.
The `token` is an HMAC-based capability tied to the file ID. It does not expire,
but it is invalidated when the org''s logo is replaced or removed — shared caches
may continue serving the old image until the `Cache-Control` max-age of one hour
elapses. The endpoint never redirects to a signed storage URL; bytes are served
inline so behavior is consistent across storage backends.
All failure modes — invalid file ID, invalid token, file not currently referenced
as an org logo — return a uniform `404` to avoid acting as an existence oracle.'
operationId: get_api_v1_files__file_org_logo
parameters:
- description: File ID of the org's logo (`fil_...`). Must be currently set as an organization's logo within the same app.
example: string
in: path
name: file
required: true
schema:
type: string
- description: HMAC capability token authorizing access to this specific file. Obtained from the `org_logo.url` minted when the logo was serialized.
example: string
in: query
name: token
required: true
schema:
type: string
responses:
'200':
content:
'*/*':
schema:
format: binary
type: string
description: Raw image bytes of the org logo, served with the file's original content type.
'404':
description: Not found
summary: Fetch an org logo image
tags:
- Files
/api/v1/files/{file}/share:
get:
description: 'Returns the raw image bytes for a file that was explicitly shared for public
access, identified by `file`. This endpoint is designed for consumers that hold
a URL far longer than a signed storage URL lives — GitHub PR bodies (whose camo
image proxy re-fetches from the origin URL), wikis, and issue trackers — and
fetch it via plain GET requests without bearer token support. Authorization is
performed via a short, stable capability `token` rather than an HTTP header.
The `token` is an HMAC-based capability tied to the file ID. It does not expire,
but it is invalidated when sharing is turned off for the file (`share: false` on
the file update endpoint) or the file is deleted — shared caches may continue
serving the bytes until the `Cache-Control` max-age of one hour elapses. The
endpoint never redirects to a signed storage URL; bytes are served inline so
behavior is consistent across storage backends. Only image content types are
served.
All failure modes — invalid file ID, invalid token, file not currently shared —
return a uniform `404` to avoid acting as an existence oracle.'
operationId: get_api_v1_files__file_share
parameters:
- description: File ID of the shared file (`fil_...`). The file must currently be marked as publicly shared.
example: string
in: path
name: file
required: true
schema:
type: string
- description: 'HMAC capability token authorizing access to this specific file. Obtained from the `share_url` returned when the file was uploaded with `share: true`.'
example: string
in: query
name: token
required: true
schema:
type: string
responses:
'200':
content:
'*/*':
schema:
format: binary
type: string
description: Raw image bytes of the shared file, served with the file's original content type.
'404':
description: Not found
summary: Fetch a publicly shared file
tags:
- Files
components:
schemas:
StorageFile:
description: A file stored in the platform's object storage, with metadata and a signed URL for downloading its contents.
example:
app: dap_0aBcDeFgHiJkLmNoPqRsTu
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
share_url: https://example.com
size: 1024
team: tem_0aBcDeFgHiJkLmNoPqRsTu
updated_at: '2024-01-01T00:00:00Z'
url: https://example.com
user: usr_0aBcDeFgHiJkLmNoPqRsTu
properties:
app:
description: ID of the app this file belongs to (`app_...`).
example: dap_0aBcDeFgHiJkLmNoPqRsTu
type: string
content_type:
description: MIME type of the file, e.g. `"image/png"` or `"application/pdf"`.
example: application/json
type: string
created_at:
description: When the file was uploaded (ISO 8601).
example: '2024-01-01T00:00:00Z'
format: date-time
type: string
filename:
description: Original filename as provided at upload time.
example: document.pdf
type: string
id:
description: File ID (`fil_...`).
example: fil_0aBcDeFgHiJkLmNoPqRsTu
type: string
image_source:
$ref: '#/components/schemas/ImageSource'
description: Image display metadata. Present only when `content_type` is an image type; `null` otherwise.
org:
description: ID of the organization that owns this file (`org_...`).
example: org_0aBcDeFgHiJkLmNoPqRsTu
type: string
sandbox:
description: ID of the sandbox this file is scoped to (`sbx_...`). `null` for files not associated with a sandbox.
example: dsb_0aBcDeFgHiJkLmNoPqRsTu
type: string
share_url:
description: 'Stable public URL for the file, fetchable without authentication. Present only when the file was shared (`share: true`); does not expire until sharing is disabled. Disabling and re-enabling sharing reactivates the same URL. `null` otherwise.'
example: https://example.com
type: string
size:
description: Size of the file in bytes.
example: 1024
type: integer
team:
description: ID of the team that owns this file (`team_...`). `null` if not team-owned.
example: tem_0aBcDeFgHiJkLmNoPqRsTu
type: string
updated_at:
description: When the file record was last modified (ISO 8601).
example: '2024-01-01T00:00:00Z'
format: date-time
type: string
url:
description: Short-lived signed URL for downloading the file. `null` if a URL could not be generated.
example: https://example.com
type: string
user:
description: ID of the user that owns this file (`user_...`). `null` if not user-owned.
example: usr_0aBcDeFgHiJkLmNoPqRsTu
type: string
required:
- id
type: object
ImageSource:
description: Resolved metadata for an image, including its delivery URL, dimensions, and optional references to the underlying storage file or media record.
example:
file: fil_0aBcDeFgHiJkLmNoPqRsTu
height: 600
media: med_0aBcDeFgHiJkLmNoPqRsTu
mime_type: application/json
refresh_url: https://example.com
url: https://example.com
width: 800
properties:
file:
description: ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.
example: fil_0aBcDeFgHiJkLmNoPqRsTu
type:
- string
- 'null'
height:
description: Height of the image in pixels. `null` if not known.
example: 600
type:
- integer
- 'null'
media:
description: ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.
example: med_0aBcDeFgHiJkLmNoPqRsTu
type:
- string
- 'null'
mime_type:
description: MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.
example: application/json
type:
- string
- 'null'
refresh_url:
description: Endpoint URL you can call to obtain a fresh signed `url` when the current one has expired. `null` if the URL does not require refreshing.
example: https://example.com
type:
- string
- 'null'
url:
description: Signed or public URL for downloading the image. May be time-limited; use `refresh_url` to obtain a new URL when this one expires.
example: https://example.com
type:
- string
- 'null'
width:
description: Width of the image in pixels. `null` if not known.
example: 800
type:
- integer
- 'null'
type: object
x-archastro-docs-scope: external
x-auth-schemes:
bearer:
description: User JWT in Authorization header
scheme: bearer
type: http
device_flow:
description: Third-party device flow token — requires per-action opt-in
scheme: bearer
type: http
x-token-use: third_party
publishable_key:
description: Publishable API key — identifies the app
in: header
name: x-archastro-api-key
prefix: pk_
type: api_key
secret_key:
description: Secret API key — full admin access, no user JWT required
in: header
name: x-archastro-api-key
prefix: sk_
type: api_key
x-channel-auth:
- bearer
x-channels:
- description: 'Authenticated collaborative editing for durable Artifacts.
The live OT revision and `dirty` flag describe synchronization, not durability.
Only `checkpointed_revision` and checkpoint events confirm a completed save;
process or node loss can discard the dirty tail after the last successful save.'
joins:
# --- truncated at 32 KB (1832 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/archastro/refs/heads/main/openapi/archastro-files-api-openapi.yml