Atom Files API

Core resources, one mental model

One namespace; multiple byte locations

Integrations address an Atom folder and file. They do not choose a Google Drive API, a Backblaze bucket, or a Mac filesystem path. Atom keeps that routing behind the API boundary.

Endpoints

Choose an endpoint to open its own reference page and shareable URL. File delivery, usage metering, and billing are separate concerns. Atom’s provider-specific queues, credentials, and internal routing stay private.

These paths are not yet served by a public Atom API. The existing Atom Drive API has different routes.

OpenAPI

The OpenAPI 3.1 JSON covers all 38 operations, request fields, response examples, status codes, and scoped bearer assumptions. Its server uses a non-working .invalid host until public API access is available.

Know which outputs are ready

Atom identifies a file’s media type from content and metadata, then applies only enabled processors that fit that version. Ask for processing status before requesting an artifact. There is no single “file processing complete” flag: OCR may be ready while a summary is still running.

Each output is tied to the immutable version_id and records its processor or model. States are not_applicable, disabled, queued, running, partial, ready, failed, or stale. New bytes create new processing state; old outputs must never appear current. Processing may occur asynchronously, and available outputs depend on policy, cost, and source availability.

A policy update uses expected_policy_revision to avoid lost edits. Cancellation may race with completion and keeps already-published outputs. Artifact deletion denies new reads and search results immediately, then confirms byte/vector purge through an operation; it suppresses automatic regeneration for that source version until an explicitly authorized rerun.

These processing and search routes describe the intended public scope; they are not available as a live API today. Processor catalog, output formats, retention, cost policy, and model version guarantees require implementation decisions.

POST /v1/uploads

Create an upload intent for a folder. Requires a future folder-scoped write credential. Returns an operation and a destination-specific transfer plan; it does not mean file bytes have been committed.

An app declares the destination, size, content hash, and retry identity. Atom decides whether the bytes can go directly to the destination or need an explicitly permitted staging route.

POST /v1/uploads
Authorization: Bearer <scoped token>
Idempotency-Key: invoice-8427
Content-Type: application/json

{
  "parent_id": "folder_123",
  "name": "invoice.pdf",
  "size_bytes": 4194304,
  "sha256": "<whole-file digest>",
  "replace_version_id": null
}

202 Accepted
{
  "operation_id": "op_456",
  "file_id": "file_789",
  "status": "ready_to_transfer",
  "transfer": {
    "method": "direct",
    "capability": "<short-lived, destination-scoped capability>"
  }
}

The transfer plan would be short-lived and destination-scoped. A client would refresh an expired plan using the same operation ID; it must not create another file to resume. A future SDK could hide transport details.

Grant a folder and only the actions needed

A user would authorize an integration for selected folders and capabilities. Example grants are files.metadata.read, files.content.read, files.analysis.read, files.analysis.manage, embeddings.read, files.write, events.read, and usage.read. Managing analysis is separate from reading its results; sensitive processing still needs explicit owner consent. Billing reads require a separate account-level administrator grant. A token must not confer access to the whole Mac, underlying provider credentials, or unrelated folders.

These scope names and the consent flow are not yet available as issued credentials.

Accepted is not available

Non-file operations such as policy changes and artifact purges finish as completed with a completion receipt. Operations can instead end as failed, cancelled, or conflict. A sender’s finish call does not by itself produce available.

Retry without duplicating or overwriting

Events are hints. The change feed is recoverable.

Subscribe to file.available, operation.failed, file.version_created, artifact.ready, artifact.purged, processing.failed, processing.cancelled, and access.revoked webhooks for fast reactions. Use the cursor-based change feed to recover missed notifications. Authorization is checked again when an app reads the file or a derived output.

{
  "id": "evt_234",
  "type": "file.available",
  "operation_id": "op_456",
  "file_id": "file_789",
  "version_id": "ver_012",
  "occurred_at": "2026-10-20T18:00:00Z"
}

The event names and shape above are examples. Webhook signatures, replay retention, and cursor expiry are not specified yet.

Handle outcomes explicitly

A caller needs to distinguish a rejected request from an accepted operation that later fails. The error envelope will be finalized alongside the implementation.

Build the smallest trustworthy API first

This sequence is not a launch date. Each stage depends on the correctness checks in the stage before it.

1. 01 · Contract

   Make the rules executable

   Define folder grants, version identity, error bodies, status codes, idempotency, and a versioned OpenAPI contract. Prove authorization and retry behavior against running services.

2. 02 · Read

   Let apps find and open files

   Ship scoped folder listing, metadata search, version-pinned reads, and byte ranges. Measure startup, seek, and fallback behavior without exposing device paths or provider credentials.

3. 03 · Write

   Make saves recoverable

   Add upload intents, destination-bound byte transfer, durable operation IDs, and destination receipts. Test offline devices, lost acknowledgements, concurrent edits, and checksum failure.

4. 04 · Understand

   Expose useful derived content

   Report per-output progress, version-pinned artifacts, embeddings, and authorized semantic results. Prove policy updates, reruns, cancellation, purging, stale-version handling, partial failures, revocation, and processor cost controls.

5. 05 · React

   Keep integrations current

   Provide a replayable change feed and signed webhooks, including artifact readiness. Verify catch-up after downtime and immediate denial after a grant is revoked.

6. 06 · Operate

   Open to external developers

   Publish onboarding, measured usage, billing visibility where needed, and generated language examples. Expand SDK support only after the HTTP contract stabilizes.