API documentation

Who has access

The API is part of the Business package. The token belongs to the subscribing account, and that account is answerable for whatever the integration does. Once you have the package, the token is under Panel → API, with examples already filled in with your own credentials.

Authentication

Every request carries the token in the Authorization header. A request with no token, or with a token from an expired subscription, gets 401.

Authorization: Bearer <token>

On servers where the Authorization header never reaches PHP — which happens with CGI and FastCGI without extra configuration — you can use X-API-Token instead. There is also ?token=, which exists for trying things out in a browser and should not be used in production: a token in the address bar ends up in server logs and in the Referer header of any outgoing link.

Responses and errors

The response is always JSON, errors included — a client that gets HTML on failure has no way of telling whoever wrote it what went wrong. An error always has this shape:

{
  "erro": {
    "codigo": "token_invalido",
    "mensagem": "Token inválido ou sem subscrição activa."
  }
}

Reading

The API sees exactly what the person sees in the panel: the business account holder and the managers see the whole team's files, everyone else sees their own.

Uploading files

Uploading is done as a session, in chunks, rather than in a single request. The reason is practical: a file of several gigabytes will not fit in one request — it runs into PHP's size and time limits and those of any proxy along the way, and when it fails at 90% there is nothing to salvage. In chunks, each request is small, and anyone who drops out resumes where they left off.

The offset parameter is optional but recommended: it says at which byte the chunk starts. If it does not match what the server already holds, the request is refused with 409 and the response carries the correct value — which is what lets you resume without sending the same chunk twice.

The same rules as uploading through the panel apply: the quota is checked when the session opens (against the declared size) and again on completion (against the real size on disk), and file types the server could execute are refused.

Full example

Uploading a file in 8 MB chunks:

TOKEN=<token>
BASE=https://www.youstorecloud.com/api/v1/
FICHEIRO=video.mp4
TAMANHO=$(stat -c%s "$FICHEIRO")

# 1. abrir a sessao
UPLOAD=$(curl -s -H "Authorization: Bearer $TOKEN" \
  -X POST "$BASE"uploads \
  -F "nome=$FICHEIRO" -F "tamanho=$TAMANHO" \
  | sed -n 's/.*"upload_id":"\([0-9a-f]*\)".*/\1/p')

# 2. enviar em pedacos de 8 MB, a partir do byte 0
split -b 8M "$FICHEIRO" parte_
OFFSET=0
for PARTE in parte_*; do
  curl -s -H "Authorization: Bearer $TOKEN" \
    -X POST "$BASE"uploads/"$UPLOAD"?offset=$OFFSET \
    -F "pedaco=@$PARTE"
  OFFSET=$((OFFSET + $(stat -c%s "$PARTE")))
done

# 3. fechar — devolve o ficheiro e o link de partilha
curl -s -H "Authorization: Bearer $TOKEN" \
  -X POST "$BASE"uploads/"$UPLOAD"/concluir

Resuming an interrupted upload

curl -s -H "Authorization: Bearer $TOKEN" "$BASE"uploads/"$UPLOAD"
# {"upload_id":"...","nome":"video.mp4","tamanho":5000000,"recebido":3200000,"falta":1800000}

# continue from the byte given in "recebido"

Limits