POST /teams/{teamId}/files/init-upload

Reservar row + emitir upload URL

Access: Signed in
Service: https://files-api.axuz.net

Accepted authentication

sessionCookie — Sessão plena Axuz (cookie de sessão da casa). Sessão restrita é 403 enrollment_required.
bearerSession — JWT de acesso da sessão em `Authorization: Bearer`.

Valida size + content_type + quota; reserva files_files pending. Devolve upload_url — presigned PUT (S3/R2) OU path proxy /teams/{teamId}/files/upload/{fileId} (Local/Bunny). ?proxy=1 força path relativo mesmo com backend remoto (útil pra clients fora do CORS allowlist do bucket).

This operation's description comes from the handler comment in the code (in Portuguese).

Parameters

Name	In	Type	Required	Description
`teamId`	path	`string`	yes
`proxy`	query	`string`	no

Request body

application/json · Required

Name	Type	Required	Description
`folder_id`	`string<uuid>`	no
`name`	`string`	yes
`content_type`	`string`	yes	MIME normalizado; validado contra allowlist.
`size_bytes`	`integer`	yes
`content_hash`	`string`	no	SHA256 hex opcional (dedup); ignorado com contexto.
`context_type`	`string`	no	Contexto privado. `task_deliverable` + `context_id` (id da tarefa) criam um arquivo de ENTREGA (também usado pela capa de tarefa): fora da listagem/busca do Drive, legível só por quem lê a tarefa, teto de 100 MB (413 acima), sem dedup. `board_image` + `context_id` (id do board) cria a capa/foto do board: só imagem (jpeg/png/webp/gif/avif, 400 fora disso), teto de 10 MB, legível só por quem alcança o board (canal vinculado, scope tasks); 404 sem acesso ao board. Arquivo privado sem referência viva vai para a lixeira pelo GC. enum: `"task_deliverable", "board_image"`
`context_id`	`string<uuid>`	no	Id da tarefa ou do board (exige `context_type`).

{
  "folder_id": "00000000-0000-0000-0000-000000000000",
  "name": "string",
  "content_type": "string",
  "size_bytes": 1,
  "content_hash": "string",
  "context_type": "task_deliverable",
  "context_id": "00000000-0000-0000-0000-000000000000"
}

Responses

201
Criado

Name	Type	Required	Description
`file`	`FilesFile`	yes
`file.id`	`string<uuid>`	yes
`file.team_id`	`string<uuid> \| null`	no	NULL em drive pessoal.
`file.folder_id`	`string<uuid> \| null`	no
`file.uploaded_by`	`string<uuid>`	no
`file.name`	`string`	yes
`file.content_type`	`string`	yes
`file.size_bytes`	`integer`	yes
`file.storage_key`	`string`	yes	Chave opaca no storage provider (S3/R2/B2/Bunny/local).
`file.status`	`string`	yes	enum: `"pending", "uploaded", "scanning", "ready", "infected"`
`file.created_at`	`string<date-time>`	yes
`file.completed_at`	`string<date-time> \| null`	no
`file.context_type`	`string \| null`	no	enum: `"bill", "receivable", "payment", "receipt", "task", "timeline_post", "wiki", "drive", null`
`file.context_id`	`string<uuid> \| null`	no
`file.context_label`	`string \| null`	no
`file.thumb_key`	`string \| null`	no
`file.thumb_width`	`integer \| null`	no
`file.thumb_height`	`integer \| null`	no
`upload_url`	`string`	yes	URL presigned PUT (S3/R2/B2) OU path relativo `/teams/.../upload/{fileId}` (Local/Bunny).
`presigned_url`	`string`	no	Alias legado; presente apenas na variante `/me/files/init-upload`.

400
Payload/params inválidos

Name	Type	Required	Description
`error`	`string`	yes	Chave/slug do erro
`message`	`string`	no

401
Sem credencial valida

Name	Type	Required	Description
`error`	`string`	yes

409
Team storage quota exceeded

Name	Type	Required	Description
`error`	`string`	yes	Chave/slug do erro
`message`	`string`	no

413
File exceeds max size

429
Limite de requisições excedido.

Name	Type	Required	Description
`error`	`string`	yes

500
Erro interno. Tente de novo com backoff; reporte o `X-Request-Id`.

Name	Type	Required	Description
`error`	`string`	yes

Examples

"Try it" is turned off in this reference. Use the examples with your test credential.

curl

curl -sS -X POST 'https://files-api.axuz.net/teams/TEAM_ID/files/init-upload' \
  -H "Authorization: Bearer $AXUZ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"folder_id":"00000000-0000-0000-0000-000000000000","name":"string","content_type":"string","size_bytes":1,"content_hash":"string","context_type":"task_deliverable","context_id":"00000000-0000-0000-0000-000000000000"}'

Node.js

const res = await fetch("https://files-api.axuz.net/teams/TEAM_ID/files/init-upload", {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.AXUZ_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "folder_id": "00000000-0000-0000-0000-000000000000",
    "name": "string",
    "content_type": "string",
    "size_bytes": 1,
    "content_hash": "string",
    "context_type": "task_deliverable",
    "context_id": "00000000-0000-0000-0000-000000000000"
  }),
});
if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);
console.log(await res.json());

Python

import os
import requests

res = requests.request(
    "POST",
    "https://files-api.axuz.net/teams/TEAM_ID/files/init-upload",
    headers={
        "Authorization": f"Bearer {os.environ['AXUZ_TOKEN']}",
    },
    json={
        "folder_id": "00000000-0000-0000-0000-000000000000",
        "name": "string",
        "content_type": "string",
        "size_bytes": 1,
        "content_hash": "string",
        "context_type": "task_deliverable",
        "context_id": "00000000-0000-0000-0000-000000000000",
    },
    timeout=30,
)
res.raise_for_status()
print(res.json())

POST /teams/{teamId}/files/init-upload

Accepted authentication

Parameters

Request body

Responses

201 Criado

400 Payload/params inválidos

401 Sem credencial valida

409 Team storage quota exceeded

413 File exceeds max size

429 Limite de requisições excedido.

500 Erro interno. Tente de novo com backoff; reporte o X-Request-Id.