Skip to main content

​
Build on Weav

The Weav Developer Platform helps you integrate AI-powered customer support directly into your product stack. Use the API to manage agents, conversations, messages, customers, companies, and training data in your workspace, with predictable, organization-scoped behavior that’s built for production integrations. Authentication is token-based and ability-scoped. Endpoints are versioned under /v1, return consistent JSON structures, and include clear error signaling—making it easier to handle retries, validation issues, and long-term maintenance as your integration grows. Webhooks complement the API by delivering real-time events to your systems when conversations, customers, agents, or training data change. Together, the API and webhooks give you the complete integration loop: send commands into Weav and react to updates from Weav in near real time.

​
What you can build

  • Sync conversations and customer records with your CRM
  • Trigger automations from live support events
  • Manage AI agents and training data programmatically
  • Build internal tooling for support operations and analytics
  1. Your app calls the Weav API to create or update resources.
  2. Weav emits webhook events as those resources change.
  3. Your backend processes events and updates your downstream systems.
  • Use idempotent handlers for webhook processing
  • Retry safely on transient failures
  • Log request IDs and event IDs for traceability

​
Authentication

The Weav External API uses Bearer token authentication with workspace-scoped API keys. All external endpoints are versioned under /v1 and require a valid token in the Authorization header. 
Authorization: Bearer YOUR_API_KEY
Your API key inherits your workspace context. Requests can only access resources within that workspace.

​
Get an API Key

You can create API keys in the Weav dashboard:
  1. Go to Settings → API Tokens
  2. Click Create API token
  3. Enter a name (and optional expiration)
  4. Create the token
  5. Copy the token immediately and store it securely
⚠️ Important
The plain-text token is shown only once at creation time.
If you lose it, delete the token and create a new one.

​
Use the Key in Requests

Example using curl: 
curl -X GET "https://api.weav.com/v1/agents" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

​
Common Authentication Failures

​
401 — Unauthenticated

Usually means the token is missing, malformed, or invalid. 
{
  "error": "Unauthenticated",
  "code": "UNAUTHENTICATED"
}

​
403 — Insufficient Token Ability

The token is valid but does not include the ability required for the HTTP method. 
{
  "error": "Token missing required ability: external-api:write",
  "code": "INSUFFICIENT_TOKEN_ABILITY"
}

​
Authentication Best Practices

  • Store API keys in a secure secrets manager (never in frontend code)
  • Set expirations where possible
  • Rotate keys regularly
  • Delete unused keys immediately
  • Send requests server-to-server over HTTPS only

​
Error handling

The Weav External API uses predictable HTTP status codes and machine-readable error codes for most authorization and business-rule failures. For client integrations, treat all non-2xx responses as failures, branch first on HTTP status, then on the error code when available. Most endpoint failures use a standard JSON envelope with error and optional code. Validation failures use Laravel’s validation shape (message + errors). A small number of endpoint-specific business-state responses may return custom payloads, so clients should handle both patterns safely.

​
Error response formats

​
Standard API error envelope

{
  "error": "Human-readable description",
  "code": "ERROR_CODE",
  "errors": {}
}
  • error (string): human-readable message
  • code (string, optional): machine-readable identifier
  • errors (object, optional): additional context/details

​
Validation errors (422)

Use this format when payload/query/path validation fails. 
{
  "message": "The given data was invalid.",
  "errors": {
    "field_name": ["Validation message"]
  }
}

​
Endpoint-specific business-state error example (422)

Some flows can return a custom shape such as: 
{
  "success": false,
  "message": "No completed URLs found to resync"
}
Treat this as a non-retryable business-state error unless your app changes input/state before retrying.

​
HTTP status codes to handle

StatusMeaningTypical causeRetry guidance
400Bad request / business rule failureInvalid assignment type, invalid type/code pathUsually no
401UnauthenticatedMissing/invalid bearer tokenNo (fix auth)
403ForbiddenMissing token ability or prohibited operationNo (fix permissions/input)
404Not foundResource missing or outside workspace scopeNo (fix ID/scope)
422Validation/business-state failureInvalid fields, unsupported stateNo (fix payload/state)
500Server errorInternal processing/creation failureSometimes (with backoff)

​
Common error codes

CodeStatusDescription
UNAUTHENTICATED401Request is not authenticated
INSUFFICIENT_TOKEN_ABILITY403Token lacks required ability (external-api:read or external-api:write)
FORBIDDEN403Operation blocked by business rule (for example protected agent operations)
RESOURCE_NOT_FOUND404Resource doesn’t exist in current workspace scope
INVALID_SENDER400Invalid message sender reference
INVALID_ASSIGNEE400Invalid assignee reference
INVALID_ASSIGNEE_TYPE400Assignee type violates conversation/channel rules
INVALID_TYPE400Unsupported training data type
INVALID_AGENT400Agent missing or outside current workspace
URL_DISCOVERY_REQUIRED422URL training must use URL process endpoint
NO_URLS_PROVIDED422URL process request had no valid URLs
PROCESSING_FAILED500URL/training processing failed server-side
CREATION_FAILED500Resource creation failed server-side

​
Best practices

  • Log status, code, and response body for all non-2xx responses.
  • Treat 4xx as request/integration issues, 5xx as transient/system issues.
  • Only retry idempotent operations, with exponential backoff and jitter.
  • Surface validation details from errors directly in developer tooling.