Files

Upload project file

POST /v1/files · uploadProjectFile

Upload an unattached standard project file. purpose defaults to project; any other purpose is refused. The ordinary default is 10 MiB; configured/admin limits apply, with a hard 16 MiB direct-body ceiling. Empty files are refused. Names are cleaned to 120 characters; bytes stay original. No idempotency deduplication. Attaching later is separate and can fail, leaving this upload to delete. Never use this route for plaintext intended for only_me protection; use encrypted vault transport.

Sign-in: a bearer credential in the Authorization header.

projectFileBearer: A live account-service sess_ session or oa_sk_ sign-in key. Cookies and oak_ keys are not accepted. File requests revalidate the session; attached files also require current project membership and, for mutations, editor/owner rights, even without the optional project query.

Parameters

Request body

Content type: application/octet-stream

Type: string (binary)

Response

201 — The requested file result.

Type: AppFileObject

Errors

Example

curl -X POST 'https://api.openagents.com/v1/files' \
  -H "Authorization: Bearer $OPENAGENTS_TOKEN" \
  -H 'Content-Type: application/octet-stream' \
  --data-binary @file

Start project file upload

POST /v1/files/uploads · startProjectFileUpload

Start a resumable standard file upload. Creator must currently edit the project. request_id is scoped to the creator and resolved project; retries with the same cleaned filename, size and SHA-256 return the existing upload (200). Conflicting reuse returns 409. Reserves the complete size against the project's storage account, not a payment. File/account limits and the default seven-day expiry are configured by the service, not by a caller-supplied admin flag.

Sign-in: a bearer credential in the Authorization header.

projectFileBearer: A live account-service sess_ session or oa_sk_ sign-in key. Cookies and oak_ keys are not accepted. File requests revalidate the session; attached files also require current project membership and, for mutations, editor/owner rights, even without the optional project query.

Request body

Content type: application/json

Type: AppFileUploadRequest

Response

200 — The requested file result.

Type: AppFileUpload

201 — The requested file result.

Type: AppFileUpload

Errors

Example

curl -X POST 'https://api.openagents.com/v1/files/uploads' \
  -H "Authorization: Bearer $OPENAGENTS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "request_id": "string",
  "project": "string",
  "filename": "string",
  "size_bytes": 1,
  "sha256": "string"
}'

Get project file upload

GET /v1/files/uploads/{upload} · getProjectFileUpload

Inspect progress. Only the creating account, still an editor/owner of the supplied project, can inspect or resume it. Current protection and configured size limits are rechecked. Expired/cancelled uploads can return 410 upload_expired; a removed session returns 404.

Sign-in: a bearer credential in the Authorization header.

projectFileBearer: A live account-service sess_ session or oa_sk_ sign-in key. Cookies and oak_ keys are not accepted. File requests revalidate the session; attached files also require current project membership and, for mutations, editor/owner rights, even without the optional project query.

Parameters

Response

200 — The requested file result.

Type: AppFileUpload

Errors

Example

curl 'https://api.openagents.com/v1/files/uploads/{upload}?project=...' \
  -H "Authorization: Bearer $OPENAGENTS_TOKEN"

Cancel project file upload

DELETE /v1/files/uploads/{upload} · cancelProjectFileUpload

Cancel an unfinished upload, remove its parts and release quota. Current creator/project rights still apply; expired uploads may be cancelled. A finished/finalizing upload returns 409: delete the file instead. A later repeated cancel can return 404 or 410. No remote process is being cancelled.

Sign-in: a bearer credential in the Authorization header.

projectFileBearer: A live account-service sess_ session or oa_sk_ sign-in key. Cookies and oak_ keys are not accepted. File requests revalidate the session; attached files also require current project membership and, for mutations, editor/owner rights, even without the optional project query.

Parameters

Response

200 — The requested file result.

Type: AppFileUploadDeleted

Errors

Example

curl -X DELETE 'https://api.openagents.com/v1/files/uploads/{upload}?project=...' \
  -H "Authorization: Bearer $OPENAGENTS_TOKEN"

Complete project file upload

POST /v1/files/uploads/{upload}/complete · completeProjectFileUpload

Verify all part bytes, total size, SHA-256, current rights, protection, capacity and credential-like text; then publish the file and attachment. An exact completed retry returns the same file (200). An interrupted finish can be retried with the same upload ID; finishing work survives expiry. A missing or wrong complete hash is an error, never an empty success.

Sign-in: a bearer credential in the Authorization header.

projectFileBearer: A live account-service sess_ session or oa_sk_ sign-in key. Cookies and oak_ keys are not accepted. File requests revalidate the session; attached files also require current project membership and, for mutations, editor/owner rights, even without the optional project query.

Parameters

Response

200 — The requested file result.

Type: AppFileObject

201 — The requested file result.

Type: AppFileObject

Errors

Example

curl -X POST 'https://api.openagents.com/v1/files/uploads/{upload}/complete?project=...' \
  -H "Authorization: Bearer $OPENAGENTS_TOKEN"

Put project file upload part

PUT /v1/files/uploads/{upload}/parts/{part} · putProjectFileUploadPart

Send the next complete part, at most 8 MiB, with X-Part-SHA256. Each part must have its exact expected length. An exact retry of a stored part is safe and does not advance progress twice; changed bytes or out-of-order parts return 409. If a concurrent update wins, inspect status before retrying. Finished/finalizing uploads refuse new parts.

Sign-in: a bearer credential in the Authorization header.

projectFileBearer: A live account-service sess_ session or oa_sk_ sign-in key. Cookies and oak_ keys are not accepted. File requests revalidate the session; attached files also require current project membership and, for mutations, editor/owner rights, even without the optional project query.

Parameters

Request body

Content type: application/octet-stream

Type: string (binary)

Response

200 — The requested file result.

Type: AppFileUpload

Errors

Example

curl -X PUT 'https://api.openagents.com/v1/files/uploads/{upload}/parts/{part}?project=...' \
  -H "Authorization: Bearer $OPENAGENTS_TOKEN" \
  -H 'X-Part-SHA256: ...' \
  -H 'Content-Type: application/octet-stream' \
  --data-binary @file

Get project file

GET /v1/files/{id} · getProjectFile

Read project-file metadata from this account, or with project from that project's storage. Shared members normally need project. A storage account cannot bypass current roles after ownership transfer or removal. Chat attachment IDs are a separate transport.

Sign-in: a bearer credential in the Authorization header.

projectFileBearer: A live account-service sess_ session or oa_sk_ sign-in key. Cookies and oak_ keys are not accepted. File requests revalidate the session; attached files also require current project membership and, for mutations, editor/owner rights, even without the optional project query.

Parameters

Response

200 — The requested file result.

Type: AppFileObject

Errors

Example

curl 'https://api.openagents.com/v1/files/{id}' \
  -H "Authorization: Bearer $OPENAGENTS_TOKEN"

Delete project file

DELETE /v1/files/{id} · deleteProjectFile

Delete a standard project file and its attachment, chunk storage and quota reservation. Current project editor/owner rights are required for attached files. A repeated deletion returns 404; partial cleanup failures return an error, so inspect state before retrying.

Sign-in: a bearer credential in the Authorization header.

projectFileBearer: A live account-service sess_ session or oa_sk_ sign-in key. Cookies and oak_ keys are not accepted. File requests revalidate the session; attached files also require current project membership and, for mutations, editor/owner rights, even without the optional project query.

Parameters

Response

200 — The requested file result.

Type: AppFileDeleted

Errors

Example

curl -X DELETE 'https://api.openagents.com/v1/files/{id}' \
  -H "Authorization: Bearer $OPENAGENTS_TOKEN"

Download project file

GET /v1/files/{id}/content · downloadProjectFile

Download the entire original file, with its MIME type, attachment filename and a SHA-256 checksum header. This header uses hex, not base64. Large files stream; a later part failure can terminate an already-started response. Verify size and SHA-256 before replacing a local destination. No byte-range contract is offered.

Sign-in: a bearer credential in the Authorization header.

projectFileBearer: A live account-service sess_ session or oa_sk_ sign-in key. Cookies and oak_ keys are not accepted. File requests revalidate the session; attached files also require current project membership and, for mutations, editor/owner rights, even without the optional project query.

Parameters

Response

200 — Whole original file bytes; see the operation's streaming/checksum contract.

Content type: */*

Type: string (binary)

Errors

Example

curl 'https://api.openagents.com/v1/files/{id}/content' \
  -H "Authorization: Bearer $OPENAGENTS_TOKEN"

List project attachments

GET /v1/projects/{project}/attachments · listProjectAttachments

List current files, documents, vault metadata and stored connected-source metadata, oldest first with ID tie breaks. Limit defaults to 100 and clamps to 1–200; after must still exist in this list. A project holds at most 200 file/document/vault attachments. Deleted vault objects are omitted. Protection describes the default for new attachments; changing it does not encrypt existing standard files.

Sign-in: a bearer credential in the Authorization header.

projectFileBearer: A live account-service sess_ session or oa_sk_ sign-in key. Cookies and oak_ keys are not accepted. File requests revalidate the session; attached files also require current project membership and, for mutations, editor/owner rights, even without the optional project query.

Parameters

Response

200 — The requested file result.

Type: AppFileAttachments

Errors

Example

curl 'https://api.openagents.com/v1/projects/{project}/attachments' \
  -H "Authorization: Bearer $OPENAGENTS_TOKEN"

Attach project file or document

POST /v1/projects/{project}/attachments · attachProjectFileOrDocument

Current editor or owner; send exactly one non-null file, document or vault ID. Direct sources are refused with use_the_sources_page. Standard files/documents cannot be added to only_me projects. Vault attachment needs the project's storage account and an existing encrypted object. Documents are new on every request. Known file/vault attachments can return 200, subject to current permissions and capacity; this is not a general mutation deduplication contract. An editor's uploaded standard file moves into the project's storage account, transferring its storage reservation.

Sign-in: a bearer credential in the Authorization header.

projectFileBearer: A live account-service sess_ session or oa_sk_ sign-in key. Cookies and oak_ keys are not accepted. File requests revalidate the session; attached files also require current project membership and, for mutations, editor/owner rights, even without the optional project query.

Parameters

Request body

Content type: application/json

Type: AppFileAttach

Response

200 — The requested file result.

Type: AppFileAttachmentResult (AppFileAttachment or AppFileDocumentAttachment or AppFileVaultAttachment)

201 — The requested file result.

Type: AppFileAttachmentResult (AppFileAttachment or AppFileDocumentAttachment or AppFileVaultAttachment)

Errors

Example

curl -X POST 'https://api.openagents.com/v1/projects/{project}/attachments' \
  -H "Authorization: Bearer $OPENAGENTS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "document": {
    "title": "Example note",
    "text": "Example text."
  }
}'

Delete project attachment

DELETE /v1/projects/{project}/attachments/{attachment} · deleteProjectAttachment

Current editor or owner. Remove a file/document/vault attachment. A standard file and its bytes are deleted; removing a vault attachment does not delete the encrypted vault object. Sources require their own delete route. Missing attachments return 404.

Sign-in: a bearer credential in the Authorization header.

projectFileBearer: A live account-service sess_ session or oa_sk_ sign-in key. Cookies and oak_ keys are not accepted. File requests revalidate the session; attached files also require current project membership and, for mutations, editor/owner rights, even without the optional project query.

Parameters

Response

200 — The requested file result.

Type: AppFileAttachmentDeleted

Errors

Example

curl -X DELETE 'https://api.openagents.com/v1/projects/{project}/attachments/{attachment}' \
  -H "Authorization: Bearer $OPENAGENTS_TOKEN"

Get project document

GET /v1/projects/{project}/documents/{document} · getProjectDocument

Read a document's text and metadata under current project membership. This does not execute a model or modify the document.

Sign-in: a bearer credential in the Authorization header.

projectFileBearer: A live account-service sess_ session or oa_sk_ sign-in key. Cookies and oak_ keys are not accepted. File requests revalidate the session; attached files also require current project membership and, for mutations, editor/owner rights, even without the optional project query.

Parameters

Response

200 — The requested file result.

Type: AppFileDocument

Errors

Example

curl 'https://api.openagents.com/v1/projects/{project}/documents/{document}' \
  -H "Authorization: Bearer $OPENAGENTS_TOKEN"