Platform API
Where to start: who you are, your organizations, every product and what an organization subscribes to.
- Address
- https://sparkyli.com/api/v1
- Plan
- Any plan, with API access switched on for the organization
- Specification
- https://sparkyli.com/api/v1/openapi.yaml
Endpoints
GET /
The directory of every API, how to sign in and where each specification is. No sign-in needed.
Answer: (top level)
| Name | Type | What it is |
|---|---|---|
| name, version | text | The directory's name and API version (v1). |
| auth | object | issuer (the sign-in address), openid_configuration (where OAuth clients find the sign-in endpoints), flows (person, program) and a note about plans and the API switch. |
| apis | list | One row per API: slug, name, status (live or planned), summary, access (read or read and write, null if not live), requires_paid_plan, sign_in (person, program), base_url and openapi (where its specification is). |
GET /products
Every product, where it lives and whether it has an API. No sign-in needed.
Answer: products (a list)
| Name | Type | What it is |
|---|---|---|
| slug, name, short_name | text | The product's id and names. |
| url | text | Where the product lives. |
| api | live, planned or none | Whether it has an API yet. |
GET /me
You, your organizations, your role in each product and whether each organization has switched API access on.
Call this first. The organization ids it returns are what you send as x-sparky-org to every other API when you belong to several.
Answer: (top level)
| Name | Type | What it is |
|---|---|---|
| user | object | id, email and name. |
| organizations | list | Each has id, name, personal (true for your own), api_access_enabled and roles (your role per product slug). |
| apis | list | The live APIs with their base_url. |
Errors (besides the common ones)
- 401 unauthorized: No token, or it is invalid or has expired.
GET /subscriptions
Plan, status and seats per product, and whether the plan includes the API.
Owners and admins only. Never payment details.
Inputs
| Name | Type | What it is |
|---|---|---|
| org_id | text | One of the ids from /me. Needed only if you belong to several organizations. |
Answer: (top level)
| Name | Type | What it is |
|---|---|---|
| organization | object | id, name and api_access_enabled. |
| subscriptions | list | Per product: product, name, plan, plan_name, status, seats and api (status, and included_in_plan: whether the plan includes the API). |
Errors (besides the common ones)
- 400 org_required: You belong to several organizations; pass org_id.
- 403 forbidden: Only an owner or admin can see subscriptions.
- 404 not_found: That is not one of your organizations.
Example
curl -s -H "authorization: Bearer $TOKEN" https://sparkyli.com/api/v1/meNew here? Start with the three things first, then sign in. Errors are explained under errors and limits.