Files API

HTTP reference for files. Read authentication and access before using these operations. All examples use made-up data and placeholder credentials.

• GET /v1/file
• DELETE /v1/file/{file_id}
• GET /v1/file/{file_id}
• DELETE /v1/file/{file_id}/link
• POST /v1/file/{file_id}/link
• POST /v1/file/upload

GET /v1/file

Get Files

Current files HTTP operation. External credential scopes: read:records. Access is resolved for the authenticated user or by the endpoint-specific OAuth checks. Pagination accepts integer skip and take; set both explicitly. An omitted value passes through to the data query. Collection property names differ by resource; use the response schema. Production rate limit: 100 requests per 15-minute window, per legacy key, otherwise per client IP. RateLimit headers report the current window; respect Retry-After on 429.

Request example

curl --fail-with-body -X GET \
  'https://api.ranch.bot/v1/file' \
  -H "Authorization: Bearer $RANCHBOT_TOKEN"

Responses

200 response schema (application/json)

{
  "total": 1,
  "files": []
}

DELETE /v1/file/{file_id}

Delete File

Current files HTTP operation. External credential scopes: write:records. Access is resolved for the authenticated user or by the endpoint-specific OAuth checks. Direct requests execute without an app confirmation screen. Production rate limit: 100 requests per 15-minute window, per legacy key, otherwise per client IP. RateLimit headers report the current window; respect Retry-After on 429. Deletion behavior is described below; a successful status does not imply erasure from all retained history. Deletes the accessible file through the file service. Marks the file inactive; do not interpret this as immediate storage erasure.

Request example

curl --fail-with-body -X DELETE \
  'https://api.ranch.bot/v1/file/<file_id>' \
  -H "Authorization: Bearer $RANCHBOT_TOKEN"

Responses

GET /v1/file/{file_id}

Get File

Current files HTTP operation. External credential scopes: read:records. Access is resolved for the authenticated user or by the endpoint-specific OAuth checks. Production rate limit: 100 requests per 15-minute window, per legacy key, otherwise per client IP. RateLimit headers report the current window; respect Retry-After on 429.

Request example

curl --fail-with-body -X GET \
  'https://api.ranch.bot/v1/file/<file_id>' \
  -H "Authorization: Bearer $RANCHBOT_TOKEN"

Responses

200 response schema (application/json)

{
  "file": {
    "id": "11111111-1111-4111-8111-111111111111",
    "created_at": "2026-09-01T12:00:00.000Z",
    "updated_at": "2026-09-01T12:00:00.000Z",
    "name": "Example",
    "is_active": true,
    "mime_type": "example",
    "size": 1,
    "url": "example"
  },
  "signedUrl": "example"
}

DELETE /v1/file/{file_id}/link

Unlink File

Current files HTTP operation. External credential scopes: write:records. Access is resolved for the authenticated user or by the endpoint-specific OAuth checks. Direct requests execute without an app confirmation screen. Production rate limit: 100 requests per 15-minute window, per legacy key, otherwise per client IP. RateLimit headers report the current window; respect Retry-After on 429. Deletion behavior is described below; a successful status does not imply erasure from all retained history. Removes the supplied associations; this is not file deletion.

Request body (application/json)

{}

Request example

curl --fail-with-body -X DELETE \
  'https://api.ranch.bot/v1/file/<file_id>/link' \
  -H "Authorization: Bearer $RANCHBOT_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{}'

Responses

200 response schema (application/json)

{
  "file": {
    "id": "11111111-1111-4111-8111-111111111111",
    "created_at": "2026-09-01T12:00:00.000Z",
    "updated_at": "2026-09-01T12:00:00.000Z",
    "name": "Example",
    "is_active": true,
    "mime_type": "example",
    "size": 1,
    "url": "example"
  }
}

POST /v1/file/{file_id}/link

Link File

Current files HTTP operation. External credential scopes: write:records. Access is resolved for the authenticated user or by the endpoint-specific OAuth checks. Direct requests execute without an app confirmation screen. Production rate limit: 100 requests per 15-minute window, per legacy key, otherwise per client IP. RateLimit headers report the current window; respect Retry-After on 429.

Request body (application/json)

{}

Request example

curl --fail-with-body -X POST \
  'https://api.ranch.bot/v1/file/<file_id>/link' \
  -H "Authorization: Bearer $RANCHBOT_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{}'

Responses

200 response schema (application/json)

{
  "file": {
    "id": "11111111-1111-4111-8111-111111111111",
    "created_at": "2026-09-01T12:00:00.000Z",
    "updated_at": "2026-09-01T12:00:00.000Z",
    "name": "Example",
    "is_active": true,
    "mime_type": "example",
    "size": 1,
    "url": "example"
  }
}

POST /v1/file/upload

Upload File

Current files HTTP operation. External credential scopes: write:records. Access is resolved for the authenticated user or by the endpoint-specific OAuth checks. Direct requests execute without an app confirmation screen. Production rate limit: 100 requests per 15-minute window, per legacy key, otherwise per client IP. RateLimit headers report the current window; respect Retry-After on 429. Accepted types: JPEG, PNG, GIF, WebP images (10 MB each); MP4, QuickTime and AVI video (100 MB each); JSON, PDF and CSV documents (5 MB each). Maximum 10 files per request.

Request body (multipart/form-data)

Request example

curl --fail-with-body -X POST \
  'https://api.ranch.bot/v1/file/upload' \
  -H "Authorization: Bearer $RANCHBOT_TOKEN" \
  -F 'files=@/path/to/example.pdf'

Responses

201 response schema (application/json)

{
  "success": true,
  "errors": [],
  "data": {
    "files": []
  }
}

400 response schema (application/json)

{
  "success": false,
  "errors": [
    {
      "message": "No files provided"
    }
  ],
  "data": null
}

Error body

Validation and authentication errors generally use this envelope. Rate-limit errors omit data; OAuth polling also has protocol-specific errors shown in its reference.

{
  "success": false,
  "errors": [
    {
      "code": 400,
      "name": "ValidationError",
      "message": "Example validation failure"
    }
  ]
}