API Reference

Programmatic access to formulate360 — build integrations, automate workflows, and manage formulations.

Last updated: September 3, 2026 · By Formulate 360 Team

⚙️ Getting Started

Base URL

https://www.formulate360.com/api/v1

Authentication

Requests authenticate via session cookies (web) or X-Api-Key header (programmatic).

curl -H "X-Api-Key: *** https://www.formulate360.com/api/v1/formulas

Response Format

Success returns data + meta. Paginated endpoints include pagination.

{"data":{...},"meta":{"request_id":"req_abc123","api_version":"v1","pagination":{"next_cursor":"str","has_more":false}}}

Error Format

Errors return error.code (machine-readable), error.message, and optional validation details.

{"error":{"code":"invalid_request","message":"Invalid payload.","details":[{"path":"name","message":"Required"}]},"meta":{"request_id":"req_abc123","api_version":"v1"}}

Idempotency

POST, PUT, and PATCH endpoints accept an Idempotency-Key header. Duplicate requests within the 24-hour window return the original response without side effects. Safe to retry on network errors.

Pagination

Cursor-based pagination. Use ?limit=N (default 50, max 200) and ?cursor=X from the meta.pagination.next_cursor field.

curl -H "X-Api-Key: *** "https://www.formulate360.com/api/v1/formulas?limit=20&cursor=2025-01-01T00:00:00Z"

Rate Limiting & Tier Gating

Per-user rate limits vary by subscription tier. AI and document generation endpoints require Pro or Enterprise. Rate-limited requests return 429 with a Retry-After header.

Quick Examples

▶ List formulas

curl -H "X-Api-Key: *** https://www.formulate360.com/api/v1/formulas

▶ Create a formula

curl -X POST -H "X-Api-Key: *** -H "Content-Type: application/json" -H "Idempotency-Key: my-key" -d '{"name":"My Formula","product_type":"topicals"}' https://www.formulate360.com/api/v1/formulas

▶ Generate a document

curl -X POST -H "X-Api-Key: *** -H "Content-Type: application/json" -d '{"formula_id":"ID","document_type":"sop"}' https://www.formulate360.com/api/v1/documents

▶ Get current identity

curl -H "X-Api-Key: *** https://www.formulate360.com/api/v1/me
Formulas10

Create, read, update, and delete formulations.

GET/api/v1/formulas
formulas.read

List all formulas for the authenticated user. Supports cursor-based pagination with `limit` and `cursor` query parameters. Results ordered by `updated_at` descending.

No request body required.

Response Schema

{"data":{"items":[{"id":"uuid","name":"str","product_type":"str","status":"str","batch_size":0,"batch_unit":"str","created_at":"str","updated_at":"str"}]},"meta":{"request_id":"str","api_version":"v1","pagination":{"next_cursor":"str|null","has_more":false}}}

cURL Example

curl -H "X-Api-Key: *** https://www.formulate360.com/api/v1/formulas?limit=20

Error Codes

CodeStatusMessage
formulas_list_failed500Internal server error while listing formulas.
POST/api/v1/formulas
formulas.write

Create a new formula. Name and product_type are required. Optionally set batch_size, batch_unit, product_id, and setup preferences. Set generate_ai_draft to true for AI-suggested ingredients. Idempotent with Idempotency-Key header.

Request Body

{"name":"My Formula","product_type":"topicals","batch_size":1000,"batch_unit":"g","generate_ai_draft":true}

Response Schema

{"data":{"formula":{"id":"uuid","name":"str","product_type":"str","status":"draft","batch_size":1000,"batch_unit":"g","created_at":"str","updated_at":"str"},"ai_draft":false},"meta":{"request_id":"str","api_version":"v1"}}

cURL Example

curl -X POST -H "X-Api-Key: *** -H "Content-Type: application/json" -H "Idempotency-Key: my-key" -d '{"name":"My Formula","product_type":"topicals"}' https://www.formulate360.com/api/v1/formulas

Error Codes

CodeStatusMessage
invalid_request400Invalid payload. Name and product type required.
tier_limit_reached403Free plan limited to 3 formulas. Upgrade to Pro.
tier_upgrade_required403AI draft requires Pro subscription.
formulas_create_failed500Internal server error.
GET/api/v1/formulas/:id
formulas.read

Retrieve a single formula by ID including all ingredient line items.

No request body required.

Response Schema

{"data":{"formula":{"id":"uuid","name":"str","product_type":"str","status":"str","description":"str|null","batch_size":1000,"batch_unit":"str","product_id":"str|null","created_at":"str","updated_at":"str"},"ingredients":[{"id":"uuid","name":"str","function":"str","percentage":0,"grams":0,"phase":"str","sort_order":0}]},"meta":{"request_id":"str","api_version":"v1"}}

cURL Example

curl -H "X-Api-Key: *** https://www.formulate360.com/api/v1/formulas/ID

Error Codes

CodeStatusMessage
not_found404Formula not found.
PUT/api/v1/formulas/:id
formulas.write

Update formula metadata. Creates a new version snapshot automatically. Supports partial update. Idempotent.

Request Body

{"name":"Updated Formula","status":"active","batch_size":2000}

Response Schema

{"data":{"formula":{"id":"uuid","name":"str","status":"active","updated_at":"str"},"version_created":true},"meta":{"request_id":"str","api_version":"v1"}}

cURL Example

curl -X PUT -H "X-Api-Key: *** -H "Content-Type: application/json" -d '{"name":"Updated Formula","status":"active"}' https://www.formulate360.com/api/v1/formulas/ID

Error Codes

CodeStatusMessage
invalid_request400Invalid payload.
not_found404Formula not found.
DELETE/api/v1/formulas/:id
formulas.write

Soft-delete a formula. Archived formulas are hidden from default listings.

No request body required.

Response Schema

{"data":{"deleted":true},"meta":{"request_id":"str","api_version":"v1"}}

cURL Example

curl -X DELETE -H "X-Api-Key: *** https://www.formulate360.com/api/v1/formulas/ID

Error Codes

CodeStatusMessage
not_found404Formula not found.
GET/api/v1/formulas/:id/versions
formulas.read

List all version snapshots for a formula, ordered by creation date descending.

No request body required.

Response Schema

{"data":{"versions":[{"id":"uuid","version_number":1,"description":"str","created_at":"str"}]},"meta":{"request_id":"str","api_version":"v1"}}

cURL Example

curl -H "X-Api-Key: *** https://www.formulate360.com/api/v1/formulas/ID/versions
POST/api/v1/formulas/:id/versions
formulas.write

Manually create a new version snapshot of the current formula state.

Request Body

{"description":"Pre-production snapshot"}

Response Schema

{"data":{"version":{"id":"uuid","version_number":3,"description":"str","created_at":"str"}},"meta":{"request_id":"str","api_version":"v1"}}

cURL Example

curl -X POST -H "X-Api-Key: *** -H "Content-Type: application/json" -d '{"description":"Pre-production snapshot"}' https://www.formulate360.com/api/v1/formulas/ID/versions
GET/api/v1/formulas/:id/versions/:vid
formulas.read

Retrieve a specific version snapshot including its frozen ingredient data.

No request body required.

Response Schema

{"data":{"version":{"id":"uuid","version_number":1,"formula_snapshot":{},"ingredients":[]}},"meta":{"request_id":"str","api_version":"v1"}}

cURL Example

curl -H "X-Api-Key: *** https://www.formulate360.com/api/v1/formulas/ID/versions/VID

Error Codes

CodeStatusMessage
not_found404Version not found.
GET/api/v1/formulas/:id/shares
formulas.read

List all share links for a formula.

No request body required.

Response Schema

{"data":{"shares":[{"id":"uuid","token":"str","expires_at":"str|null","created_at":"str"}]},"meta":{"request_id":"str","api_version":"v1"}}

cURL Example

curl -H "X-Api-Key: *** https://www.formulate360.com/api/v1/formulas/ID/shares
POST/api/v1/formulas/:id/shares
formulas.write

Create a share link for a formula. Optionally set expiration in days.

Request Body

{"expires_in_days":7}

Response Schema

{"data":{"share":{"id":"uuid","token":"abc123","url":"https://formulate360.com/shared/abc123","expires_at":"str","created_at":"str"}},"meta":{"request_id":"str","api_version":"v1"}}

cURL Example

curl -X POST -H "X-Api-Key: *** -H "Content-Type: application/json" -d '{"expires_in_days":7}' https://www.formulate360.com/api/v1/formulas/ID/shares
Projects6

Organize formulas into project workspaces.

GET/api/v1/projects
projects.read

List all projects for the authenticated user.

No request body required.

Response Schema

{"data":{"items":[{"id":"uuid","name":"str","description":"str|null","primary_formula_id":"uuid|null","created_at":"str"}]},"meta":{"request_id":"str","api_version":"v1"}}

cURL Example

curl -H "X-Api-Key: *** https://www.formulate360.com/api/v1/projects
POST/api/v1/projects
projects.write

Create a new project workspace. Name is required. Idempotent.

Request Body

{"name":"Summer 2025 Line","description":"New moisturizer product line"}

Response Schema

{"data":{"id":"uuid","name":"str","description":"str|null","created_at":"str"},"meta":{"request_id":"str","api_version":"v1"}}

cURL Example

curl -X POST -H "X-Api-Key: *** -H "Content-Type: application/json" -H "Idempotency-Key: my-key" -d '{"name":"Summer 2025 Line","description":"New moisturizer line"}' https://www.formulate360.com/api/v1/projects

Error Codes

CodeStatusMessage
invalid_request400Invalid payload.
GET/api/v1/projects/:id
projects.read

Retrieve a project by ID including its linked formulas.

No request body required.

Response Schema

{"data":{"project":{"id":"uuid","name":"str","description":"str|null","created_at":"str"},"formulas":[]},"meta":{"request_id":"str","api_version":"v1"}}

cURL Example

curl -H "X-Api-Key: *** https://www.formulate360.com/api/v1/projects/ID

Error Codes

CodeStatusMessage
not_found404Project not found.
PUT/api/v1/projects/:id
projects.write

Update project metadata. Supports partial updates. Idempotent.

Request Body

{"name":"Updated Project","description":"Updated description"}

Response Schema

{"data":{"id":"uuid","name":"str","updated_at":"str"},"meta":{"request_id":"str","api_version":"v1"}}

cURL Example

curl -X PUT -H "X-Api-Key: *** -H "Content-Type: application/json" -d '{"name":"Updated Project"}' https://www.formulate360.com/api/v1/projects/ID

Error Codes

CodeStatusMessage
not_found404Project not found.
DELETE/api/v1/projects/:id
projects.write

Delete a project. Does not delete linked formulas, only unlinks them.

No request body required.

Response Schema

{"data":{"deleted":true},"meta":{"request_id":"str","api_version":"v1"}}

cURL Example

curl -X DELETE -H "X-Api-Key: *** https://www.formulate360.com/api/v1/projects/ID

Error Codes

CodeStatusMessage
not_found404Project not found.
POST/api/v1/projects/:id/formulas
projects.write

Link one or more formulas to a project workspace.

Request Body

{"formula_ids":["uuid-1","uuid-2"]}

Response Schema

{"data":{"linked":2},"meta":{"request_id":"str","api_version":"v1"}}

cURL Example

curl -X POST -H "X-Api-Key: *** -H "Content-Type: application/json" -d '{"formula_ids":["uuid-1","uuid-2"]}' https://www.formulate360.com/api/v1/projects/ID/formulas
Chemicals & Suppliers2

Browse the global chemical library and manage supplier catalogs.

GET/api/v1/chemicals
chemicals.read

List chemicals from the global library. Supports search, category, and INCI name query filters.

No request body required.

Response Schema

{"data":{"items":[{"id":"uuid","name":"str","inci_name":"str","category":"str","functions":["str"]}]},"meta":{"request_id":"str","api_version":"v1"}}

cURL Example

curl -H "X-Api-Key: *** "https://www.formulate360.com/api/v1/chemicals?category=emollients&limit=30"
GET/api/v1/suppliers
chemicals.read

List suppliers and their catalog items. Supports search by name.

No request body required.

Response Schema

{"data":{"items":[{"id":"uuid","name":"str","catalog_count":0}]},"meta":{"request_id":"str","api_version":"v1"}}

cURL Example

curl -H "X-Api-Key: *** "https://www.formulate360.com/api/v1/suppliers?search=essential"
Documents5

Generate, list, and download formulation documents (SOPs, COAs, spec sheets).

GET/api/v1/documents
documents.read

List all generated documents. Filter by document_type, status, or formula_id.

No request body required.

Response Schema

{"data":{"items":[{"id":"uuid","document_type":"str","title":"str","status":"str","formula_id":"uuid","created_at":"str"}]},"meta":{"request_id":"str","api_version":"v1"}}

cURL Example

curl -H "X-Api-Key: *** "https://www.formulate360.com/api/v1/documents?document_type=sop"
POST/api/v1/documents
documents.write

Generate a new document for a formula. Document type determines template. Returns job ID. Idempotent.

Request Body

{"formula_id":"uuid","document_type":"sop","title":"Manufacturing SOP"}

Response Schema

{"data":{"job_id":"uuid","document_id":"uuid","status":"pending"},"meta":{"request_id":"str","api_version":"v1"}}

cURL Example

curl -X POST -H "X-Api-Key: *** -H "Content-Type: application/json" -d '{"formula_id":"ID","document_type":"sop","title":"Manufacturing SOP"}' https://www.formulate360.com/api/v1/documents

Error Codes

CodeStatusMessage
tier_upgrade_required403Document generation requires Pro subscription.
GET/api/v1/documents/:id
documents.read

Retrieve document metadata and current generation status.

No request body required.

Response Schema

{"data":{"id":"uuid","document_type":"str","title":"str","status":"str","content_url":"str|null","error":"str|null","created_at":"str","updated_at":"str"},"meta":{"request_id":"str","api_version":"v1"}}

cURL Example

curl -H "X-Api-Key: *** https://www.formulate360.com/api/v1/documents/ID

Error Codes

CodeStatusMessage
not_found404Document not found.
DELETE/api/v1/documents/:id
documents.write

Soft-delete a document.

No request body required.

Response Schema

{"data":{"deleted":true},"meta":{"request_id":"str","api_version":"v1"}}

cURL Example

curl -X DELETE -H "X-Api-Key: *** https://www.formulate360.com/api/v1/documents/ID

Error Codes

CodeStatusMessage
not_found404Document not found.
GET/api/v1/documents/:id/download
documents.read

Get a pre-signed download URL for the generated document. Returns a 302 redirect.

No request body required.

Response Schema

Redirect (302) to pre-signed download URL

cURL Example

curl -H "X-Api-Key: *** https://www.formulate360.com/api/v1/documents/ID/download

Error Codes

CodeStatusMessage
not_found404Document not found.
document_not_ready400Generation not yet complete.
AI & Intelligence1

AI-powered formulation features including SOP generation and compliance checks.

POST/api/v1/ai/sop
ai.sop

Generate a Standard Operating Procedure (SOP) from a formula. Requires Pro or Enterprise subscription. Idempotent.

Request Body

{"formula_id":"uuid","format":"detailed","include_safety":true}

Response Schema

{"data":{"sop":{"title":"str","content":"str (markdown)","sections":[]},"job_id":"uuid"},"meta":{"request_id":"str","api_version":"v1"}}

cURL Example

curl -X POST -H "X-Api-Key: *** -H "Content-Type: application/json" -d '{"formula_id":"ID","format":"detailed"}' https://www.formulate360.com/api/v1/ai/sop

Error Codes

CodeStatusMessage
tier_upgrade_required403AI features require Pro subscription.
rate_limited429Rate limit exceeded.
Jobs4

Track async operations like document generation, AI processing, and exports.

POST/api/v1/jobs
jobs.write

Create an async job. Returns job ID, initial status, and SSE events URL for real-time progress. Idempotent.

Request Body

{"job_type":"document_generation","payload":{"formula_id":"uuid","document_type":"sop"}}

Response Schema

{"data":{"job_id":"uuid","status":"pending","events_url":"/api/v1/jobs/ID/events","created_at":"str"},"meta":{"request_id":"str","api_version":"v1"}}

cURL Example

curl -X POST -H "X-Api-Key: *** -H "Content-Type: application/json" -d '{"job_type":"document_generation","payload":{"formula_id":"ID"}}' https://www.formulate360.com/api/v1/jobs

Error Codes

CodeStatusMessage
invalid_request400Invalid payload.
GET/api/v1/jobs/:id
jobs.read

Get the current status, progress, and result of an async job.

No request body required.

Response Schema

{"data":{"id":"uuid","job_type":"str","status":"str","progress":50,"result":null,"error":"str|null","created_at":"str","completed_at":"str|null"},"meta":{"request_id":"str","api_version":"v1"}}

cURL Example

curl -H "X-Api-Key: *** https://www.formulate360.com/api/v1/jobs/ID

Error Codes

CodeStatusMessage
not_found404Job not found.
POST/api/v1/jobs/:id
jobs.write

Cancel a pending or running job. Terminal-state jobs (completed/failed) cannot be cancelled.

Request Body

{"action":"cancel"}

Response Schema

{"data":{"id":"uuid","status":"cancelled"},"meta":{"request_id":"str","api_version":"v1"}}

cURL Example

curl -X POST -H "X-Api-Key: *** -H "Content-Type: application/json" -d '{"action":"cancel"}' https://www.formulate360.com/api/v1/jobs/ID

Error Codes

CodeStatusMessage
not_found404Job not found.
job_not_cancellable400Job is already in a terminal state.
GET/api/v1/jobs/:id/events
jobs.read

Server-Sent Events (SSE) stream of job progress. Connect with EventSource or curl for real-time monitoring.

No request body required.

Response Schema

text/event-stream — each event has event type, data payload, and optional progress field

cURL Example

curl -H "X-Api-Key: *** -H "Accept: text/event-stream" https://www.formulate360.com/api/v1/jobs/ID/events

Error Codes

CodeStatusMessage
not_found404Job not found.
Exports1

Export formulas in multiple formats for external use.

POST/api/v1/exports
exports.write

Export a formula to PDF, CSV, JSON, or Excel. Returns a job ID — use Jobs API for progress and download URL. Idempotent.

Request Body

{"formula_id":"uuid","format":"pdf","include_ingredients":true,"include_cost":true}

Response Schema

{"data":{"job_id":"uuid","status":"pending","format":"pdf"},"meta":{"request_id":"str","api_version":"v1"}}

cURL Example

curl -X POST -H "X-Api-Key: *** -H "Content-Type: application/json" -d '{"formula_id":"ID","format":"pdf","include_ingredients":true}' https://www.formulate360.com/api/v1/exports

Error Codes

CodeStatusMessage
invalid_request400Invalid format or missing fields.
tier_upgrade_required403Export requires Pro subscription.
Webhooks6

Configure webhook endpoints to receive real-time events for formula changes, document generation, and more.

GET/api/v1/webhooks
webhooks.read

List all webhook configurations for your organization. Requires organization context.

No request body required.

Response Schema

{"data":{"webhooks":[{"id":"uuid","name":"str","endpoint_url":"str","events":["str"],"active":true,"created_at":"str"}]},"meta":{"request_id":"str","api_version":"v1"}}

cURL Example

curl -H "X-Api-Key: *** https://www.formulate360.com/api/v1/webhooks

Error Codes

CodeStatusMessage
org_required400Organization required to manage webhooks.
POST/api/v1/webhooks
webhooks.write

Create a new webhook configuration. A signing secret is generated and returned once. Supports events: formula.*, document.*, batch.*, and more.

Request Body

{"name":"My Webhook","endpoint_url":"https://example.com/hook","events":["formula.created","formula.updated"]}

Response Schema

{"data":{"id":"uuid","name":"str","endpoint_url":"str","events":["str"],"secret":"whsec_...","active":true,"created_at":"str"},"meta":{"request_id":"str","api_version":"v1"}}

cURL Example

curl -X POST -H "X-Api-Key: *** -H "Content-Type: application/json" -d '{"name":"My Webhook","endpoint_url":"https://example.com/hook","events":["formula.created","formula.updated"]}' https://www.formulate360.com/api/v1/webhooks

Error Codes

CodeStatusMessage
invalid_request400Invalid webhook payload.
org_required400Organization required.
GET/api/v1/webhooks/:id
webhooks.read

Get a single webhook configuration.

No request body required.

Response Schema

{"data":{"id":"uuid","name":"str","endpoint_url":"str","events":["str"],"active":true,"custom_headers":{}},"meta":{"request_id":"str","api_version":"v1"}}

cURL Example

curl -H "X-Api-Key: *** https://www.formulate360.com/api/v1/webhooks/ID

Error Codes

CodeStatusMessage
not_found404Webhook not found.
PUT/api/v1/webhooks/:id
webhooks.write

Update webhook configuration: endpoint URL, events, active status, custom headers.

Request Body

{"endpoint_url":"https://example.com/new-hook","events":["formula.created","formula.deleted"],"active":true}

Response Schema

{"data":{"id":"uuid","updated_at":"str"},"meta":{"request_id":"str","api_version":"v1"}}

cURL Example

curl -X PUT -H "X-Api-Key: *** -H "Content-Type: application/json" -d '{"active":false}' https://www.formulate360.com/api/v1/webhooks/ID

Error Codes

CodeStatusMessage
not_found404Webhook not found.
DELETE/api/v1/webhooks/:id
webhooks.write

Delete a webhook configuration. Future events will not be delivered.

No request body required.

Response Schema

{"data":{"deleted":true},"meta":{"request_id":"str","api_version":"v1"}}

cURL Example

curl -X DELETE -H "X-Api-Key: *** https://www.formulate360.com/api/v1/webhooks/ID

Error Codes

CodeStatusMessage
not_found404Webhook not found.
GET/api/v1/webhooks/:id/deliveries
webhooks.read

List recent delivery attempts with status, HTTP response code, and timestamp.

No request body required.

Response Schema

{"data":{"deliveries":[{"id":"uuid","event_type":"str","status":"str","http_status":200,"attempted_at":"str"}]},"meta":{"request_id":"str","api_version":"v1"}}

cURL Example

curl -H "X-Api-Key: *** https://www.formulate360.com/api/v1/webhooks/ID/deliveries
Organizations2

Manage organizations for team-based collaboration.

GET/api/v1/organizations
organizations.read

List organizations the authenticated user belongs to.

No request body required.

Response Schema

{"data":{"items":[{"id":"uuid","name":"str","role":"str","created_at":"str"}]},"meta":{"request_id":"str","api_version":"v1"}}

cURL Example

curl -H "X-Api-Key: *** https://www.formulate360.com/api/v1/organizations
POST/api/v1/organizations
organizations.write

Create a new organization. The creator becomes the owner. Idempotent.

Request Body

{"name":"My Formulation Lab"}

Response Schema

{"data":{"id":"uuid","name":"str","role":"owner","created_at":"str"},"meta":{"request_id":"str","api_version":"v1"}}

cURL Example

curl -X POST -H "X-Api-Key: *** -H "Content-Type: application/json" -d '{"name":"My Formulation Lab"}' https://www.formulate360.com/api/v1/organizations
Authentication & Identity1

Get the current authenticated profile and identity.

GET/api/v1/me
identity.read

Retrieve the current authenticated user profile including subscription tier, organization memberships, and usage limits.

No request body required.

Response Schema

{"data":{"id":"uuid","email":"str","full_name":"str|null","subscription_tier":"str","subscription_status":"str","organizations":[{"id":"uuid","name":"str","role":"str"}],"formula_count":5,"formula_limit":10},"meta":{"request_id":"str","api_version":"v1"}}

cURL Example

curl -H "X-Api-Key: *** https://www.formulate360.com/api/v1/me

Error Codes

CodeStatusMessage
auth_required401Authentication required.
Published March 15, 2025· Last updated September 3, 2026· By Formulate 360 Team

Content developed by formulation chemists and reviewed for accuracy. Formulate360 is an AI-powered formulation workspace — AI-generated output should be reviewed by qualified professionals before production use.