Skip to main content
Uppzy M2M API is designed for server-to-server integrations. A typical integration:
  1. Authenticates with an API key
  2. Targets a specific tenant and site
  3. Uploads or manages reference content
  4. Sends chat requests
  5. Tracks quality with feedback, sessions, and statistics

​
Base URL

https://api.uppzy.com/api/v1

​
Authentication model

All M2M requests require an API key in the request headers. 
X-API-Key: <YOUR_API_KEY>
Read API Authentication before implementing your client.

​
Main resource model

Most M2M integrations work with three identifiers:
  • tenant_id: the workspace-level scope
  • site_id: the website or chatbot scope
  • session_id: the conversation scope
In practice:
  • Tenant endpoints are useful for limits and account-level checks
  • Site endpoints are used for documents, chat, sessions, and statistics
  • Session IDs help you keep conversation continuity for a user or channel

​
Endpoint families

​
Tenant endpoints

Use tenant endpoints for environment checks and account-level information. Common use cases:
  • Verify limits before traffic starts
  • Check usage at workspace level
  • Confirm tenant-level statistics
Reference:

​
Document endpoints

Use document endpoints to load the content the assistant should rely on. Supported flows include:
  • Upload file document
  • Create text document
  • Create Q&A document
Reference:

​
Chat endpoints

Use chat endpoints to send messages to the assistant. Two main patterns:
  • Sync chat: request and answer in one round trip
  • Async chat: submit request now, poll for completion later
Reference:

​
Session and analytics endpoints

Use these endpoints to observe real usage and integration quality. Reference: For a new integration, use this sequence:
  1. Authenticate with an API key
  2. Validate tenant connectivity with a read request
  3. Lock the correct tenant_id and site_id in configuration
  4. Upload a small approved document set
  5. Send a sync chat request as a smoke test
  6. Add async chat if your workload needs queue-friendly handling
  7. Collect feedback and read statistics to monitor quality
This flow keeps your first production rollout easy to verify.

​
Sync chat vs async chat

​
Sync chat

Use sync chat when:
  • You need the answer immediately
  • Request volume is moderate
  • Your caller can wait for the response
Example request: 
{
  "session_id": "user-123-web",
  "message": "How does the return process work?",
  "email": "user@example.com",
  "response_language": "en"
}
Typical sync response: 
{
  "session_id": "user-123-web",
  "request_id": "req_abc123",
  "answer": "Returns are accepted within the published return window.",
  "confidence_level": "high",
  "confidence_score": 92
}

​
Async chat

Use async chat when:
  • You want non-blocking request handling
  • Your application already uses job or queue patterns
  • You need polling or background processing
Typical async sequence:
  1. POST /m2m/sites/{id}/chat/async
  2. Read request_id
  3. Poll GET /m2m/sites/{id}/chat/requests/{requestId}
  4. Stop polling when status is complete or failed
Initial async response: 
{
  "request_id": "req_abc123",
  "session_id": "user-123-web",
  "status": "pending"
}
Status response after completion: 
{
  "request_id": "req_abc123",
  "session_id": "user-123-web",
  "status": "completed",
  "answer": "Returns are accepted within the published return window."
}

​
Session strategy

Choose a stable session_id strategy before going live. Good examples:
  • Per website visitor
  • Per authenticated customer
  • Per support thread
  • Per messaging channel user
Keep the strategy stable enough that follow-up questions stay in the correct conversation context.

​
Document strategy

Document quality directly affects answer quality. Recommended document rollout:
  1. Start with a small approved set
  2. Prefer clean policy, support, and FAQ material
  3. Review results before large-scale ingestion
  4. Add Q&A entries for repeated direct questions
Example text document payload: 
{
  "title": "Support Hours",
  "content": "Support is available Monday to Friday between 09:00 and 18:00.",
  "category": "support"
}
Example Q&A payload: 
{
  "title": "Delivery FAQ",
  "question": "Do you offer same-day delivery?",
  "answer": "Availability depends on location and order timing.",
  "category": "faq"
}

​
Error handling model

Use your HTTP client to separate retryable and non-retryable failures. Typical handling:
  • 400: fix payload or request structure
  • 401: fix API key or authentication setup
  • 403: check plan, access, or allowed capability
  • 404: check tenant ID, site ID, or resource ownership
  • 429: retry with backoff
  • 5xx: use bounded retries and alerting
Do not blindly retry every failure class.

​
Observability model

Track at minimum:
  • Success and failure rate by endpoint
  • Latency by endpoint
  • 429 and 5xx trends
  • Async completion time
  • Chat quality signals from feedback and statistics
If your integration is production-critical, add per-environment dashboards and alerts from day one.

​
Suggested reading order

  1. API Authentication
  2. M2M Code Samples
  3. M2M Integration Guidelines
  4. API Reference