Skip to content
API referenceFiles API

Get multiple files

For AI assistants: the facts every SparkLayer API call needs
  • Base URLs: Live https://app.sparklayer.io, test https://test.app.sparklayer.io. Each environment has its own data and its own API keys.
  • Access: API access needs the Pro or Enterprise plan. Create credentials (Site ID, Client ID, Client Secret) in the SparkLayer Dashboard at Settings > API.
  • Access token: POST {base}/api/auth/token with a Site-Id header and a JSON body (not form-encoded): {"grant_type":"client_credentials","client_id":"…","client_secret":"…"}. It returns access_token, valid for 3,600 seconds. There is no refresh token: cache the token and request a new one shortly before it expires.
  • Every request: Authorization: Bearer <access_token> and Site-Id: <site id>, plus Content-Type: application/json when there is a body. Set a User-Agent that names your integration.
  • Errors: RFC 7807 problem details: title, status, detail and an optional errors[] of { code, message, property }. Some error responses have no body. Retry 5xx, 429 (honouring Retry-After) and concurrent-update 409s with exponential backoff; on 401, get a new token once and retry; don't retry other 4xx without changing the request.
  • Pagination: Most list endpoints return everything. GET /api/v2/price-lists pages with page and page_size (up to 250) until pagination.current_page equals total_pages. GET /api/v1/purchases uses limit (up to 500) and offset: stop when a page has fewer than limit results.
  • Ground rules: Use only endpoints, fields and SDK methods that the docs or OpenAPI specs define. Prefer GET /api/v2/price-lists over the deprecated v1. Products are matched by SKU. Keep credentials in environment variables or a secrets manager, never in code.
  • Read the docs as Markdown: Add .md to any page URL. Index of every page: docs.sparklayer.io/llms.txt. Every API operation, compactly: docs.sparklayer.io/llms-api.txt. The developer guides in full: docs.sparklayer.io/developers/llms.txt.
  • OpenAPI specs: core, ordering, pricing, purchasing, stock, files, sync-log: https://docs.sparklayer.io/openapi/<api>.yaml (also .json). Ignite: https://docs.sparklayer.io/openapi/ignite.yaml.
  • MCP: Search and read these docs from your assistant with the docs MCP server at https://docs.sparklayer.io/mcp.
Build with AI: ready-made prompts and MCP setup
GET
/api/v1/files

Returns the files whose IDs you pass in ids; repeat the parameter for each ID (?ids=…&ids=…). IDs that do not exist, or whose files have been deleted or have expired, are left out of the response. If any requested file failed its post-upload checks, the whole request returns 410.

Authorization

bearerAuth
AuthorizationBearer <token>

Send Authorization: Bearer <access_token>, together with your Site-Id header, on every request. Get the token from POST /api/auth/token with your Site ID in the Site-Id header and a JSON body (not form-encoded, so standard OAuth 2.0 client libraries don't work): {"grant_type": "client_credentials", "client_id": "…", "client_secret": "…"}. Tokens are valid for 3,600 seconds and there is no refresh token: request a new one shortly before it expires. Create API credentials in the SparkLayer Dashboard under Settings > API. See Authentication.

In: header

Query Parameters

ids*array<>

The IDs of the files to get. Repeat the parameter for each ID (?ids=…&ids=…).

Formatuuid

Header Parameters

Site-Id*string

Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard.

Response Body

application/json

application/problem+json

curl -X GET "https://app.sparklayer.io/api/v1/files?ids=86027e2c-e853-11ee-b1d4-7c214a6ed8c7" \  -H "Authorization: Bearer <ACCESS_TOKEN>" \  -H "Site-Id: jones-climbing"
{  "file_handle": {    "file_path": "folder/file.png",    "id": "86027e2c-e853-11ee-b1d4-7c214a6ed8c7",    "url": "https://files.sparklayer.io/siteId/siteEnv/path/to/file.png.",    "required_headers": [      {        "name": "Content-Type",        "value": "application/pdf"      }    ]  },  "ready": true,  "mime_type": "image/png",  "file_size": 255,  "created_at": "2020-01-01T00:00:00+02:00",  "updated_at": "2020-01-01T00:00:00+02:00",  "metadata": {    "sparklayer": {      "forms": {        "context": "email_template",        "step_id": "erkjs"      },      "emails": {        "attachments": [          "86027e2c-e853-11ee-b1d4-7c214a6ed8c7"        ]      }    }  }}

Files API

Upload, update and download files with the SparkLayer Files API using expiring URLs, and retrieve order file attachments from their GIDs. Lists all endpoints.

POSTCreate a file

Registers a file and returns a signed upload URL. Upload the contents with an HTTP `PUT` to `url`, sending the `required_headers`, within 15 minutes; files can be up to 20 MB. The file type comes from the extension in `file_path` and must be on the allowed list (including PDF, CSV, common image formats and Office documents). Once uploaded, the contents are checked against the extension and the file becomes `ready` when the checks pass. Set `expires_at` to have the file deleted automatically.