API Reference#

Outeract provides a GraphQL API for managing your messaging infrastructure.

API Endpoints#

API	Base URL	Authentication
GraphQL (Developer)	`https://api.outeract.com/`	API Key
GraphQL (Admin)	`https://api.outeract.com/admin/graphql`	JWT

Authentication#

API Keys (Developer API)#

Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Note: API keys are scoped to a specific application, so the X-Outeract-App-ID header is not required.

JWT Tokens (Admin API)#

For admin operations, use JWT authentication:

Authorization: Bearer YOUR_JWT_TOKEN

Quick Reference#

Common Headers#

Header	Value	Required
`Authorization`	`Bearer <token>`	Yes
`X-Outeract-App-ID`	Your application ID	JWT only*
`Content-Type`	`application/json`	Yes

*API keys are already scoped to an application.

Rate Limits#

Tier	Requests/minute	Burst
Free	60	10
Pro	600	100
Enterprise	6000	1000

Rate limit headers are included in responses:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 599
X-RateLimit-Reset: 1699574400

API Sections#

GraphQL API #

Primary API for all operations:

Schema exploration
Queries and mutations
Pagination patterns
Error handling

Webhooks #

Receive real-time events:

Inbound messages
Delivery status
Signature verification
Retry policies

Outbound Webhooks #

Subscribe to events:

Event patterns
Payload format
Managing subscriptions
Debugging

Code Examples#

Send a Message#

mutation SendMessage {
  sendMessage(
    platformConnectionId: "pc_abc123"
    toExternalId: "+14155551234"
    message: "Hello from Outeract!"
  ) {
    id
    status {
      success
      externalMessageId
    }
  }
}

Query Events#

query RecentEvents {
  events(
    filters: {
      eventType: { contains: "message" }
    }
    first: 20
    orderBy: { field: CREATED_AT, direction: DESC }
  ) {
    edges {
      node {
        id
        eventType
        payload
        createdAt
        edges {
          edgeType
          targetPlatformUser {
            externalId
          }
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Create a Log#

mutation CreateLog {
  createLog(
    message: "Processing started for user request"
    logLevel: "info"
    logType: "execution"
    payload: {step: "initialization", duration_ms: 42}
    eventId: "123e4567-e89b-12d3-a456-426614174000"
  ) {
    id
    createdAt
    message
    logLevel
  }
}

Error Handling#

GraphQL Errors#

{
  "data": null,
  "errors": [
    {
      "message": "Platform connection not found",
      "locations": [{"line": 2, "column": 3}],
      "path": ["sendMessage"],
      "extensions": {
        "code": "NOT_FOUND",
        "http": {"status": 404}
      }
    }
  ]
}

Error Codes#

Code	HTTP Status	Description
`UNAUTHORIZED`	401	Invalid or missing authentication
`FORBIDDEN`	403	Insufficient permissions
`NOT_FOUND`	404	Resource not found
`VALIDATION_ERROR`	400	Invalid request parameters
`RATE_LIMITED`	429	Too many requests
`INTERNAL_ERROR`	500	Server error
`PLATFORM_ERROR`	502	Platform API error

SDKs and Libraries#

Official SDKs#

Coming soon:

Python SDK
Node.js SDK
Go SDK

Community Libraries#

Check our GitHub for community-contributed libraries.

Testing#

Sandbox Mode#

Test without sending real messages:

mutation {
  sendMessage(
    platformConnectionId: "pc_abc123"
    toExternalId: "+14155551234"
    message: "Test message"
    sandbox: true
  ) {
    id
    status {
      success
    }
  }
}

Webhook Testing#

Use tools like webhook.site or ngrok for local development.