Skip to main content

Playground 1.1.0

Start the contract mock with pnpm --filter @ao/developer-gateway mock, then try each request in order. Put a token from POST /oauth/token in ACCESS_TOKEN. The same requests work against the sandbox with a sandbox app's credentials and the sandbox base URL from the reference.

This page lists copy-ready requests only; it does not call the API from your browser. The portal's Content-Security-Policy has no connect-src to a third-party or API origin, so an in-page "Try it" console is not offered here (see Security & data -- tracked as a future decision, not a current capability).

Operations​

GET /developer/v1/capabilities​

Inspect availability flags. Access: public metadata.

curl -sS -X GET 'http://127.0.0.1:4331/developer/v1/capabilities'

Answer 200: an object with api_version, environment, capabilities. Refusals are application/problem+json with a code (see errors).

GET /developer/v1/regions​

Countries with listed cities, from the reviewed registry. Access: public metadata.

curl -sS -X GET 'http://127.0.0.1:4331/developer/v1/regions'

Answer 200: an object with api_version, data, next_cursor. Refusals are application/problem+json with a code (see errors).

GET /developer/v1/status​

Developer API readiness and the public platform status. Access: public metadata.

curl -sS -X GET 'http://127.0.0.1:4331/developer/v1/status'

Answer 200: an object with api_version, environment, status, production_ready, platform. Refusals are application/problem+json with a code (see errors).

GET /developer/v1/cities​

Read reviewed city metadata. Access: scope city.public.read.

curl -sS -X GET 'http://127.0.0.1:4331/developer/v1/cities' \
  -H 'Authorization: Bearer $ACCESS_TOKEN'

Answer 200: an object with api_version, data, next_cursor. Refusals are application/problem+json with a code (see errors).

GET /developer/v1/.well-known/oauth-authorization-server​

OAuth 2.0 authorization server metadata (RFC 8414). Access: public metadata.

curl -sS -X GET 'http://127.0.0.1:4331/developer/v1/.well-known/oauth-authorization-server'

Answer 200: an object with issuer, authorization_endpoint, token_endpoint, revocation_endpoint, response_types_supported, grant_types_supported, code_challenge_methods_supported, token_endpoint_auth_methods_supported, revocation_endpoint_auth_methods_supported, scopes_supported. Refusals are application/problem+json with a code (see errors).

POST /developer/v1/oauth/token​

Issue an access token (RFC 6749). Access: client authentication (client_id + client_secret).

curl -sS -X POST 'http://127.0.0.1:4331/developer/v1/oauth/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode "client_id=$CLIENT_ID" \
  --data-urlencode "client_secret=$CLIENT_SECRET" \
  --data-urlencode 'scope=city.public.read'

Answer 200: an object with access_token, token_type, expires_in, scope, refresh_token. Refusals are application/problem+json with a code (see errors).

POST /developer/v1/oauth/revoke​

Revoke a refresh token or a user access token (RFC 7009). Access: client authentication (client_id + client_secret).

curl -sS -X POST 'http://127.0.0.1:4331/developer/v1/oauth/revoke' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode "token=$ACCESS_TOKEN" \
  --data-urlencode "client_id=$CLIENT_ID" \
  --data-urlencode "client_secret=$CLIENT_SECRET"

Answer 200: no body. Refusals are application/problem+json with a code (see errors).

GET /developer/v1/me​

The consented profile of the authorising player. Access: scope profile.basic.read.

curl -sS -X GET 'http://127.0.0.1:4331/developer/v1/me' \
  -H 'Authorization: Bearer $ACCESS_TOKEN'

Answer 200: an object with api_version, sub, display_name. Refusals are application/problem+json with a code (see errors).