API Overview

The Spalce API is a resource-oriented HTTP API that uses standard verbs, conventional status codes, and JSON for both request and response bodies. All requests must be made over TLS 1.2 or higher — plaintext requests are refused at the load balancer. Every endpoint is documented with a request schema, a response schema, and at least one runnable example.

Base URL and versioning

The base URL embeds the major version. We commit to no breaking changes within a major version, and we keep a minimum of twelve months of overlap when we cut a new one. Within a version, additive changes — new endpoints, new optional fields, new enum values — can land at any time, so always ignore unknown fields when deserializing.

# Production
https://api.spalce.dev/v1

# Sandbox
https://sandbox.spalce.dev/v1

Anatomy of a request

A typical request carries four headers: Authorization for credentials, Content-Type for the body format, Spalce-Version to pin a minor revision, and Idempotency-Key for safe retries on mutating endpoints. The Spalce-Version header is optional — if you omit it, you get the latest stable revision of your major version.

curl -X POST https://api.spalce.dev/v1/orders \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -H "Spalce-Version: 2026-05-01" \
  -H "Idempotency-Key: order-create-7f2c3a1b" \
  -d '{ "customer": "cus_01HE7K8R...", "amount": 12000, "currency": "GHS" }'

Resource shape

Every resource we return has the same top-level fields: id, object, created, livemode, and metadata. The id is a Crockford-base32 ULID, sortable by creation time. The object field is the resource type so polymorphic responses are unambiguous. livemode tells you whether the resource came from sandbox or production — a small but load-bearing detail when you are debugging a customer report.

{
  "id": "ord_01HE9X2N4MWVQRP8YZK3JTBHA7",
  "object": "order",
  "created": "2026-05-18T14:22:08Z",
  "livemode": true,
  "customer": "cus_01HE7K8R9XGTQXJN3M2WVYBPD4",
  "amount": 12000,
  "currency": "GHS",
  "status": "pending",
  "metadata": {}
}

Verbs and semantics

• GET — safe and idempotent. Never has side effects.
• POST — creates a resource or invokes an action. Combine with Idempotency-Key for safety.
• PATCH — partial updates with merge semantics. Send only the fields you want to change.
• DELETE — removes a resource. Idempotent — second call returns the same 200.

Where to go next

Once you are comfortable with the basics, dig into Pagination for high-volume reads, Errors for the standard error envelope, and Rate Limits for the bucket sizes that govern every endpoint.