Build with Matrix Tools and Transfer

Get a Key

Create a Key under Your API keys for your personal space, or under a Workspace's own developer page for a company Workspace (its Owner and Admins may create them). The secret is shown once, when the Key is created or rotated; Matrix keeps only a hash of it. Keep it in your server's secret store or an environment variable, never in a public page, a mobile app, a browser or a Git repository.

A Key belongs to one Space. A personal Key acts as you; a Workspace Key acts as the Workspace itself, so its Transfers belong to the Workspace, use the Workspace's allowance, and keep working when the person who created the Key leaves.

Each Key carries the Scopes you chose:

Calling

The base address is https://api.matrixai.group. Every call carries the Key in the X-Matrix-API-Key header. Never put the secret in a URL: it would end up in logs and browser history.

curl https://api.matrixai.group/v1/transfer/allowance \
  -H "X-Matrix-API-Key: $MATRIX_API_KEY"

Answers use one envelope. A success is { "data": …, "meta": { "request_id": "…" } }; a failure is { "code": "…", "message": "…", "details": { … }, "request_id": "…" }. Quote the request id when you report a problem.

Calls that create something take an Idempotency-Key header: a repeat of the same call with the same value answers the first result instead of doing the work twice.

Send files

Four steps: create the Transfer, ask for upload URLs, upload the bytes, complete. The files never pass through the API; they go straight to storage.

1. Create the Transfer

Declare every file with its path, size and type. The answer carries the Transfer, its id, its share_url and one item per file with the item's id.

curl -X POST https://api.matrixai.group/v1/transfer/transfers \
  -H "X-Matrix-API-Key: $MATRIX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "content-type: application/json" \
  -d '{
    "title": "Site photos",
    "message": "The north elevation, as discussed.",
    "expires_in_days": 3,
    "items": [
      { "relative_path": "north elevation.jpg", "bytes": 482913, "content_type": "image/jpeg" }
    ]
  }'

expires_in_days must be one the plan allows (1 or 3 on Free; 1, 3 or 7 with Transfer Plus and Team). A password may be set with "password". A personal Key may send from a Workspace it belongs to by adding "workspace_id"; a Workspace Key sends from its own Workspace and rejects any other.

2. Ask for upload URLs

One item at a time. The answer says the mode (single or multipart), the part_size_bytes for multipart, and a list of parts, each with part_number, url, method, headers and expires_at.

curl -X POST https://api.matrixai.group/v1/transfer/transfers/$TRANSFER_ID/parts \
  -H "X-Matrix-API-Key: $MATRIX_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "item_id": "'"$ITEM_ID"'" }'

3. Upload the bytes

PUT each part to its URL with the headers the answer gave, and keep the ETag of each response. A single-mode item is one PUT of the whole file. URLs are short-lived; ask for them again if an upload takes too long.

curl -X PUT "$PART_URL" \
  -H "content-type: image/jpeg" \
  --data-binary @"north elevation.jpg" -D -

4. Complete

Send every item with the SHA-256 of its bytes and the parts you uploaded. The answer is 202: the files are being scanned, and the Transfer becomes ready when the scan passes. A file with a malware signature, or bytes that do not match the checksum, makes the Transfer blocked.

curl -X POST https://api.matrixai.group/v1/transfer/transfers/$TRANSFER_ID/complete \
  -H "X-Matrix-API-Key: $MATRIX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "content-type: application/json" \
  -d '{
    "items": [
      {
        "item_id": "'"$ITEM_ID"'",
        "checksum": { "algorithm": "sha256", "value": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08" },
        "parts": [ { "part_number": 1, "etag": "\"d41d8cd98f00b204e9800998ecf8427e\"" } ]
      }
    ]
  }'

Read, list, allowance

Read one Transfer to see its status (created, uploading, scanning, ready, blocked, expired, revoked), its share_url and its download count. Poll it after completing to learn when the link works.

curl https://api.matrixai.group/v1/transfer/transfers/$TRANSFER_ID \
  -H "X-Matrix-API-Key: $MATRIX_API_KEY"

List Transfers newest first. limit is at most 200; the answer's meta.next_cursor goes into cursor for the next page. status narrows the list. A Workspace Key lists that Workspace; an Owner's or Admin's Key sees every Transfer of it, a Member's Key only its own.

curl "https://api.matrixai.group/v1/transfer/transfers?limit=50&status=ready" \
  -H "X-Matrix-API-Key: $MATRIX_API_KEY"

Read the Allowance to see what is left this month before sending something large. A free Workspace has no allowance of its own and spends its Owner's personal one, whose totals only the Owner sees, signed in: to a Key of such a Workspace, and to the Owner's own personal Key in either space, limit_bytes, reserved_bytes, used_bytes and remaining_bytes carry no number, and space_used_bytes and space_reserved_bytes say what the Key's space sent this month. A send that does not fit is still refused with QUOTA_EXCEEDED.

curl https://api.matrixai.group/v1/transfer/allowance \
  -H "X-Matrix-API-Key: $MATRIX_API_KEY"

Revoke

Revoking stops new downloads at once; the files are deleted within the hour, and a download already running may finish within two minutes. A Transfer revoked before its link was ready gives its reserved bytes back to the month's allowance; once the link has been ready, those bytes stay counted as sent.

curl -X POST https://api.matrixai.group/v1/transfer/transfers/$TRANSFER_ID/revoke \
  -H "X-Matrix-API-Key: $MATRIX_API_KEY"

Errors

Limits and what is not here

A Key allows 120 requests a minute unless you chose otherwise, and lives 90 days unless you chose otherwise (a year at most). Sizes and the monthly allowance follow the plan of the Space the Key belongs to, exactly as they do in the browser. Rotating a Key issues a new secret and lets the old one work for up to a day, so a running integration never has a gap.

Not in this first part: projects, a separate test environment with sandbox data, an API wallet with its own balance and per-call prices, and webhooks. Matrix Transfer has a web API and a connection for AI assistants such as ChatGPT and Claude (connect). The Matrix Tools on this site run in your browser, on your own device; 50 of them also run on our server through the Matrix Tools API, and in ChatGPT and Claude through the same connection.

Create an API Key