API reference

All SoftSolz APIs share the same auth, error and pagination shapes. Learn once, integrate anywhere.

Base URL

https://app.softsolz.uk/api/services/<service-id>/...

Public v1 endpoints live under /api/v1/services/<service-id>/.... Internal cookie-auth endpoints are not part of the public contract.

Headers

Header	Required	Use
`Authorization: Bearer sk_…`	Yes	Identify your tenant + scope.
`Content-Type: application/json`	POST/PATCH	JSON body.
`Idempotency-Key: <uuid>`	Recommended	Safe retries - see below.
`X-Request-Id: <uuid>`	Optional	Echoed back as `Softsolz-Request-Id`.

Idempotency

Add the same Idempotency-Key on a retry - we return the original response instead of acting twice. Keys are scoped to method + path + body hash, kept for 24 h.

Replaying the same key with a different body returns 409 idempotency_key_conflict.

Pagination

GET /api/v1/services/forms/forms?limit=50&offset=0

List responses include meta.has_more so you can stop paging without an extra round-trip:

{
  "data": [ ... ],
  "meta": { "limit": 50, "offset": 0, "has_more": true }
}

Rate limits

Each key has a rate_limit_per_minute (default 60). Responses include:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 47
X-RateLimit-Reset: 1715600000

Over the limit → 429 + Retry-After seconds.

Error shape

{
  "error": {
    "code": "validation_failed",
    "message": "Field 'email' is required.",
    "details": [ ... ]
  }
}

Common codes:

validation_failed - 400 - request body invalid.
invalid_api_key - 401
insufficient_scope - 403
not_found - 404
idempotency_key_conflict - 409
rate_limit_exceeded - 429
internal_error - 500

Versioning

Stable APIs live under /api/v1/.... Breaking changes ship as /api/v2/... with a 12-month deprecation window. Endpoints emit Deprecation + Sunset headers when scheduled for removal.

Forms endpoints

Full request and response shapes are on the Forms API page.

Method & path	Scope	Does
`GET /api/v1/services/forms/forms`	`service.forms.view`	List forms with counts.
`GET /api/v1/services/forms/forms/by-slug/:slug`	`service.forms.view`	Fetch a form definition by slug.
`POST /api/v1/services/forms/forms`	`service.forms.manage`	Create a form.
`PATCH /api/v1/services/forms/forms/:id`	`service.forms.manage`	Update a form.
`DELETE /api/v1/services/forms/forms/:id`	`service.forms.manage`	Delete a form.
`GET /api/v1/services/forms/forms/:id/submissions`	`service.forms.view`	List submissions for a form.
`GET /api/v1/services/forms/forms/:id/submissions/:subId`	`service.forms.view`	Read a submission (marks it read).
`PATCH /api/v1/services/forms/forms/:id/submissions/:subId`	`service.forms.submissions.manage`	Mark a submission read/unread.
`DELETE /api/v1/services/forms/forms/:id/submissions/:subId`	`service.forms.submissions.manage`	Delete a submission.
`GET /api/v1/services/forms/forms/:id/submissions.csv`	`service.forms.export`	Export submissions as CSV.
`POST /api/v1/services/forms/forms/:slug/submit`	`service.forms.submit`	Submit a response to a published form.

Blogs endpoints

Full request and response shapes are on the Blogs API page.

Method & path	Scope	Does
`GET /api/v1/services/blogs/posts/published`	`service.blogs.read`	List published posts.
`GET /api/v1/services/blogs/posts/published/:slug`	`service.blogs.read`	Fetch a published post by slug.
`GET /api/v1/services/blogs/posts`	`service.blogs.view`	List posts of any status.
`GET /api/v1/services/blogs/posts/:id`	`service.blogs.view`	Fetch a post by id.
`POST /api/v1/services/blogs/posts`	`service.blogs.manage`	Create a draft post.
`PATCH /api/v1/services/blogs/posts/:id`	`service.blogs.manage`	Update a post.
`POST /api/v1/services/blogs/posts/:id/status`	`service.blogs.publish`	Publish, schedule or archive a post.
`DELETE /api/v1/services/blogs/posts/:id`	`service.blogs.manage`	Delete a post.
`GET /api/v1/services/blogs/subscribers`	`service.blogs.view`	List subscribers.
`POST /api/v1/services/blogs/subscribers`	`service.blogs.manage`	Add a subscriber.
`PATCH /api/v1/services/blogs/subscribers/:id`	`service.blogs.manage`	Update a subscriber status.
`DELETE /api/v1/services/blogs/subscribers/:id`	`service.blogs.manage`	Delete a subscriber.
`GET /api/v1/services/blogs/analytics`	`service.blogs.view`	Blog analytics.
`GET /api/v1/services/blogs/categories`	`service.blogs.view`	Categories in use.

Payments endpoints

The Payments service exposes these public v1 endpoints. Full request and response shapes are on the Payments API page.

Method & path	Scope	Does
`POST /api/v1/services/payments/checkout-sessions`	`service.payments.checkout.create`	Create a hosted Checkout session for a one-off payment.
`GET /api/v1/services/payments/payment-links`	`service.payments.links.read`	List the payment links in your workspace.
`GET /api/v1/services/payments/payment-links/:id`	`service.payments.links.read`	Fetch a single payment link by id.
`POST /api/v1/services/payments/payment-links`	`service.payments.links.write`	Create a reusable payment link.
`PATCH /api/v1/services/payments/payment-links/:id`	`service.payments.links.write`	Update an existing payment link.

Per-service references

📝