Your first API call

TODO: replace before launch. This guide is real and it works — but it walks the template’s own /me endpoint, which is plumbing rather than product. Keep it as the model for how a guide is written, and replace the subject with a task a customer actually performs.

This is the worked example the rest of the guides should look like: one task, end to end, including the ways it fails.

What you need

An account that is signed in, with an active organisation (Quickstart).
The API host, api.scaling.cloud. It is separate from the web application and carries no /api prefix.

Check the API is alive

/health is public and takes no authentication. Start here, because it separates “the service is down” from “my credential is wrong”.

curl -s https://api.scaling.cloud/health

Response

{
  "status": "ok",
  "commit": "9f2c1ab"
}

commit is the revision currently serving. Quote it in bug reports — it is the difference between a fixed bug and a stale deployment.

Read the signed-in user

/me requires an authenticated caller and an active organisation. Authenticating means signing in with OAuth, which is described in the API reference.

curl -s https://api.scaling.cloud/me \
  -H "Authorization: Bearer $ACCESS_TOKEN"

TODO: replace before launch — the OAuth flow that produces $ACCESS_TOKEN is not settled, and neither is the shape of the token it returns. This example assumes a bearer token because that is the OAuth default, not because it is decided.

Response

{
  "userId": "user_2abc...",
  "organisationId": "org_2xyz...",
  "email": "ada@example.com",
  "name": "Ada Lovelace",
  "role": "admin"
}

name is nullable — an account that has never set one returns null. Render around that rather than asserting it.

organisationId is taken from the verified credential and never from anything the caller sends. Passing an organisation in a body, query string or header does nothing, by design.

When it fails

Every endpoint returns the same error shape, so one handler covers all of them:

401

{
  "code": "unauthenticated",
  "message": "...",
  "requestId": "..."
}

Code	Status	What to do
`unauthenticated`	401	Send the user back to sign-in
`forbidden`	403	Signed in, not allowed. Do not retry
`not_found`	404	The thing you asked for does not exist in this organisation
`invalid_request`	400	The request failed validation. Fix it; retrying will not help
`conflict`	409	Something changed underneath you. Re-read, then retry
`internal`	500	Our side. Report it with the `requestId`

Branch on code, never on message. Messages are written for humans and get rewritten; codes are part of the contract and changing one is a breaking change.

TODO: replace before launch — link the guide a reader would genuinely want next.

Get started

Guides

Your first API call

What you need

Check the API is alive

Read the signed-in user

When it fails

Next

​What you need

​Check the API is alive

​Read the signed-in user

​When it fails

​Next

What you need

Check the API is alive

Read the signed-in user

When it fails

Next