Create a file
For AI assistants: the facts every SparkLayer API call needs
- Base URLs: Live
https://app.sparklayer.io, testhttps://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/tokenwith aSite-Idheader and a JSON body (not form-encoded):{"grant_type":"client_credentials","client_id":"…","client_secret":"…"}. It returnsaccess_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>andSite-Id: <site id>, plusContent-Type: application/jsonwhen there is a body. Set aUser-Agentthat names your integration. - Errors: RFC 7807 problem details:
title,status,detailand an optionalerrors[]of{ code, message, property }. Some error responses have no body. Retry5xx,429(honouringRetry-After) and concurrent-update409s with exponential backoff; on401, get a new token once and retry; don't retry other4xxwithout changing the request. - Pagination: Most list endpoints return everything.
GET /api/v2/price-listspages withpageandpage_size(up to 250) untilpagination.current_pageequalstotal_pages.GET /api/v1/purchasesuseslimit(up to 500) andoffset: stop when a page has fewer thanlimitresults. - Ground rules: Use only endpoints, fields and SDK methods that the docs or OpenAPI specs define. Prefer
GET /api/v2/price-listsover 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
.mdto 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.
POST /api/v1/files Files API
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.
Authorization
bearerAuth 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
Header Parameters
Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
The path to the file, including the file name
An optional RFC3339 date string indicating when a file should be auto deleted
date-timeMetadata attached to the file
Response Body
application/json
application/problem+json
curl -X POST "https://app.sparklayer.io/api/v1/files" \ -H "Authorization: Bearer <ACCESS_TOKEN>" \ -H "Site-Id: jones-climbing" \ -H "Content-Type: application/json" \ -d '{ "file_path": "folder/file.png", "expires_at": "2017-07-21T17:32:28Z", "metadata": { "sparklayer": { "forms": { "context": "email_template", "step_id": "erkjs" }, "emails": { "attachments": [ "86027e2c-e853-11ee-b1d4-7c214a6ed8c7" ] } } } }'{ "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" } ]}