Projects API reference

The Socra project service — account-local cloud/developer containers.

Published contracts: @socra/project-api@0.0.3.

Authenticated request and response

Use an access token for the Account whose Projects you intend to list. A Project is an Account-local boundary. Project creation does not certify that every enabled service is ready.

This illustrative read uses an existing access token. Set ACCESS_TOKEN through your authorized credential provider; keep it out of source, logs and shared shell history. The identifiers and response below are fictional, validated against the published package. They are not a runtime execution receipt.

curl --fail-with-body --silent --show-error \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header 'Accept: application/json' \
  'https://project.socra.cloud/v1/projects?limit=1'

Example successful response body:

{
  "data": [
    {
      "id": "proj_01m00000000000000000000000",
      "slug": "example-project",
      "status": "active",
      "created_at": "2026-10-20T12:00:00.000Z",
      "updated_at": "2026-10-20T12:00:00.000Z"
    }
  ],
  "has_more": false
}

For body requests, send JSON with Content-Type: application/json and the exact body fields listed under the operation. Required scopes, when declared, appear with the operation. A token and a valid request shape do not replace the service's authorization rules.

Handle unsuccessful responses

Inspect the HTTP status and response body before taking another action. The published API client retains status, method, URL and body on APIError. It accepts a JSON error object with optional error, message, code and details fields; it also preserves a text or empty body. The method contracts below do not declare a complete per-operation error catalog.

An illustrative JSON error body (field names follow the client contract; the message is an example):

{
  "message": "The request was rejected. Check the status and service permissions."
}

• For 400 or another validation response, compare the named field, required fields, types, bounds and accepted values with this reference before correcting the request.
• For 401, obtain or refresh your token through the supported authorization path. Never paste a token into a bug report.
• For 403, stop and ask the resource owner to verify the intended principal, Account or Project, required permission and service enablement. An access denial is not evidence of a runtime defect.
• For 404, verify the exact resource identifier and Account or Project context with its owner; do not recreate a resource merely because a read failed.
• For 429, follow Retry-After if the service supplies it. These contracts specify no universal rate limit or retry interval.
• For a 5xx response or interrupted connection after a write, inspect supported resource state before retrying. The effect may be uncertain; automatic replay can duplicate work.

These are status-based troubleshooting steps, not a promise that each operation returns each status or the sample body. Preserve the exact status and redacted body when requesting help.