Read number status and API capabilities

Use GET /v1/developer/instance with instance:read to inspect the number bound to your key. You cannot select another number or workspace.

The response contains the internal number ID, connection status, inbound handler mode, recognized granted scopes and apiAvailable. It contains no phone number, provider account IDs, credentials or internal diagnostics.

apiAvailable means only that the number is connected and uses Developer API handling. Every operation still checks its own scope. Sending also checks consent, quality, service windows and other technical safety rules.

This endpoint can diagnose a disconnected number or a different inbound handler. Revoked keys, inactive workspaces and deleted numbers remain inaccessible. Other scoped reads can also remain available for retained data in either handler mode. Sends and resource mutations retain their write gates; apiAvailable is not a read-permission or send-eligibility decision. This route uses the shared read limits and returns Cache-Control: no-store.

Every request uses Authorization: Bearer $WAARU_API_KEY and a connected number in Developer API mode. The scope below is required. IDs and payloads are illustrative; replace them with your own permitted resources. See authentication and common errors, size limits and retries.

`GET /v1/developer/instance`

Required scope: instance:read

Requires instance:read. Available even when the bound number is disconnected or not in EXTERNAL_API mode. apiAvailable reports connection and handler mode only, never permission to send. No credentials, provider identifiers or diagnostics are returned.

No path or query parameters.

Request

curl --fail-with-body --request GET 'https://api.waaru.app/v1/developer/instance' \
  --header "Authorization: Bearer $WAARU_API_KEY"

Send no request body.

Response: HTTP 200

{
  "instance": {
    "id": "instance_example",
    "status": "DISCONNECTED",
    "inboundHandlerMode": "EXTERNAL_API"
  },
  "scopes": [
    "instance:read"
  ],
  "apiAvailable": false
}

Response body fields
Field	Required	Type and constraints
`instance`	Yes	`{"type":"object","required":["id","status","inboundHandlerMode"],"additionalProperties":false}` Nested fields are in the complete schema below.
`scopes`	Yes	`{"type":"array"}` Nested fields are in the complete schema below.
`apiAvailable`	Yes	`{"type":"boolean"}`

Response body: complete JSON schema

Required fields appear in required. Omit optional fields unless needed. Null is accepted only where the schema includes it. Arrays describe their elements in items; variants appear in anyOf or oneOf.

{
  "type": "object",
  "properties": {
    "instance": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 191
        },
        "status": {
          "enum": [
            "DISCONNECTED",
            "CONNECTING",
            "CONNECTED",
            "UNAUTHORIZED"
          ]
        },
        "inboundHandlerMode": {
          "type": "string"
        }
      },
      "required": [
        "id",
        "status",
        "inboundHandlerMode"
      ],
      "additionalProperties": false
    },
    "scopes": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "apiAvailable": {
      "type": "boolean"
    }
  },
  "required": [
    "instance",
    "scopes",
    "apiAvailable"
  ],
  "additionalProperties": false
}

Failures use a stable code and safe message. They never expose internal exception messages, traces or provider diagnostics. Check the error reference before retrying. An inaccessible resource can return 404 even if its identifier exists elsewhere.

Number status

GET /v1/developer/instance

Request

Response: HTTP 200

`GET /v1/developer/instance`