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

How API + webhooks work together

Your app calls the Weav API to create or update resources.
Weav emits webhook events as those resources change.
Your backend processes events and updates your downstream systems.

Integration best practices

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:

Go to Settings → API Tokens
Click Create API token
Enter a name (and optional expiration)
Create the token
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

Status	Meaning	Typical cause	Retry guidance
400	Bad request / business rule failure	Invalid assignment type, invalid type/code path	Usually no
401	Unauthenticated	Missing/invalid bearer token	No (fix auth)
403	Forbidden	Missing token ability or prohibited operation	No (fix permissions/input)
404	Not found	Resource missing or outside workspace scope	No (fix ID/scope)
422	Validation/business-state failure	Invalid fields, unsupported state	No (fix payload/state)
500	Server error	Internal processing/creation failure	Sometimes (with backoff)

Common error codes

Code	Status	Description
`UNAUTHENTICATED`	401	Request is not authenticated
`INSUFFICIENT_TOKEN_ABILITY`	403	Token lacks required ability (`external-api:read` or `external-api:write`)
`FORBIDDEN`	403	Operation blocked by business rule (for example protected agent operations)
`RESOURCE_NOT_FOUND`	404	Resource doesn’t exist in current workspace scope
`INVALID_SENDER`	400	Invalid message sender reference
`INVALID_ASSIGNEE`	400	Invalid assignee reference
`INVALID_ASSIGNEE_TYPE`	400	Assignee type violates conversation/channel rules
`INVALID_TYPE`	400	Unsupported training data type
`INVALID_AGENT`	400	Agent missing or outside current workspace
`URL_DISCOVERY_REQUIRED`	422	URL training must use URL process endpoint
`NO_URLS_PROVIDED`	422	URL process request had no valid URLs
`PROCESSING_FAILED`	500	URL/training processing failed server-side
`CREATION_FAILED`	500	Resource 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.

API documentation

Agents

Companies

Conversations

Customers

Messages

Training Data

Webhooks

Introduction

Build on Weav

What you can build

Authentication

Get an API Key

Use the Key in Requests

Common Authentication Failures

401 — Unauthenticated

403 — Insufficient Token Ability

Authentication Best Practices

Error handling

Error response formats

Standard API error envelope

Validation errors (422)

Endpoint-specific business-state error example (422)

HTTP status codes to handle

Common error codes

Best practices

​Build on Weav

​What you can build

​Authentication

​Get an API Key

​Use the Key in Requests

​Common Authentication Failures

​401 — Unauthenticated

​403 — Insufficient Token Ability

​Authentication Best Practices

​Error handling

​Error response formats

​Standard API error envelope

​Validation errors (422)

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

​HTTP status codes to handle

​Common error codes

​Best practices

Build on Weav

What you can build

Authentication

Get an API Key

Use the Key in Requests

Common Authentication Failures

401 — Unauthenticated

403 — Insufficient Token Ability

Authentication Best Practices

Error handling

Error response formats

Standard API error envelope

Validation errors (422)

Endpoint-specific business-state error example (422)

HTTP status codes to handle

Common error codes

Best practices