> ## Documentation Index
> Fetch the complete documentation index at: https://learn.orbexa.io/llms.txt
> Use this file to discover all available pages before exploring further.

# ORBEXA API reference and rate limiting

> Complete ORBEXA API endpoint catalog — authentication methods, rate limiting policies, request examples, and error handling reference.

# API Reference and Rate Limiting

## Authentication Methods

ORBEXA supports three authentication methods:

### API Key Authentication

Used for MCP tool calls and API access:

```
Authorization: Bearer YOUR_API_KEY
```

API keys are automatically generated when a merchant connects, and can also be created and managed manually in the console.

### OAuth Authentication

Used for platform integrations such as Shopify, following the standard OAuth 2.0 flow.

### Plugin Header Authentication

Used for WordPress plugin integration, requiring the following headers:

* `X-Plugin-Platform` -- Platform identifier
* `X-Plugin-Version` -- Plugin version number

## Complete Endpoint Catalog

### UCP Endpoints

| Endpoint                    | Method | Auth    | Description                     |
| --------------------------- | ------ | ------- | ------------------------------- |
| `/.well-known/ucp`          | GET    | None    | UCP discovery document          |
| `/ucp/v1/products`          | GET    | API Key | Product listing (JSON/TSV)      |
| `/ucp/v1/products/:id`      | GET    | API Key | Product details (with variants) |
| `/ucp/v1/search`            | GET    | API Key | Full-text product search        |
| `/ucp/v1/checkout-sessions` | POST   | API Key | Create checkout session         |
| `/ucp/v1/manifest`          | GET    | API Key | Merchant capability declaration |
| `/ucp/acp-feed.json`        | GET    | API Key | ACP-formatted product feed      |

### ACP Endpoints -- JSON-RPC 2.0

| Method                  | Auth    | Description            |
| ----------------------- | ------- | ---------------------- |
| `commerce.search`       | API Key | Product search         |
| `commerce.product`      | API Key | Product details        |
| `commerce.checkout`     | API Key | Initiate checkout      |
| `commerce.order_status` | API Key | Order status query     |
| `commerce.capabilities` | API Key | Capability declaration |

### ACP Endpoints -- REST

| Endpoint           | Method | Auth    | Description        |
| ------------------ | ------ | ------- | ------------------ |
| `/acp/v1/products` | GET    | API Key | Product listing    |
| `/acp/v1/checkout` | POST   | API Key | Checkout operation |

### MCP Endpoints

| Endpoint             | Method | Auth    | Description      |
| -------------------- | ------ | ------- | ---------------- |
| `/api/mcp/tools`     | GET    | API Key | Tool listing     |
| `/api/mcp/execute`   | POST   | API Key | Execute tool     |
| `/api/mcp/resources` | GET    | API Key | Resource listing |
| `/api/mcp/usage`     | GET    | API Key | Usage statistics |
| `/api/mcp/prompts`   | GET    | API Key | Prompt listing   |

### Discovery Endpoints

| Endpoint           | Method | Auth | Description            |
| ------------------ | ------ | ---- | ---------------------- |
| `/.well-known/ucp` | GET    | None | UCP protocol discovery |
| `/.well-known/acp` | GET    | None | ACP protocol discovery |
| `/.well-known/mcp` | GET    | None | MCP protocol discovery |

### OTR Endpoints

| Endpoint                  | Method | Auth | Description                       |
| ------------------------- | ------ | ---- | --------------------------------- |
| `/api/otr/verify/:domain` | GET    | None | Query domain trust score          |
| `/.well-known/otr/verify` | GET    | None | Standardized trust query endpoint |

### Shopify Integration

| Endpoint               | Method | Auth           | Description                            |
| ---------------------- | ------ | -------------- | -------------------------------------- |
| Shopify OAuth Callback | GET    | OAuth          | Handles Shopify authorization callback |
| Shopify Webhooks       | POST   | HMAC Signature | Receives Shopify event notifications   |

### WooCommerce Integration

| Endpoint                                        | Method | Auth                   | Description           |
| ----------------------------------------------- | ------ | ---------------------- | --------------------- |
| `/api/integrations/woocommerce/connect`         | POST   | API Key                | Connect store         |
| `/api/integrations/woocommerce/test`            | POST   | API Key                | Test connection       |
| `/api/integrations/woocommerce/sync/products`   | POST   | API Key                | Sync products         |
| `/api/integrations/woocommerce/sync/orders`     | POST   | API Key                | Sync orders           |
| `/api/integrations/woocommerce/sync/inventory`  | POST   | API Key                | Sync inventory        |
| `/api/integrations/woocommerce/webhooks/setup`  | POST   | API Key                | Register Webhooks     |
| `/api/integrations/woocommerce/webhooks/handle` | POST   | Signature Verification | Handle Webhook events |

### WordPress Integration

| Endpoint                                 | Method | Auth        | Description          |
| ---------------------------------------- | ------ | ----------- | -------------------- |
| `/api/integrations/wordpress/connect`    | POST   | Header Auth | One-click connection |
| `/api/integrations/wordpress/status`     | POST   | Header Auth | Query status         |
| `/api/integrations/wordpress/disconnect` | POST   | Header Auth | Disconnect           |

## Rate Limiting Policies

ORBEXA enforces tiered rate limiting to ensure fair usage and platform stability:

| Endpoint Type     | Rate Limit   | Notes                                        |
| ----------------- | ------------ | -------------------------------------------- |
| UCP endpoints     | 100 req/min  | Primary access point for AI agents           |
| API endpoints     | 60 req/min   | General API calls                            |
| Auth endpoints    | 10 req/min   | Sensitive operations like login/registration |
| Webhook endpoints | 200 req/min  | Receiving platform event notifications       |
| WordPress plugin  | 3 req/min/IP | Plugin connection and status queries         |

When rate limits are exceeded, the API returns HTTP 429 status codes. Clients should implement exponential backoff retry strategies.

## Error Handling

### Rate Limit Errors

When a request exceeds the rate limit, the API returns HTTP 429 status code:

```json theme={null}
{
  "error": "rate_limit_exceeded",
  "retry_after": 30
}
```

The `retry_after` field indicates the number of seconds the client should wait before retrying.

### Authentication Errors

| Status Code | Error          | Description                                               |
| ----------- | -------------- | --------------------------------------------------------- |
| 401         | `unauthorized` | Missing or invalid authentication credentials             |
| 403         | `forbidden`    | Valid credentials but no access to the requested resource |

### General Errors

| Status Code | Error            | Description                |
| ----------- | ---------------- | -------------------------- |
| 400         | `bad_request`    | Invalid request parameters |
| 404         | `not_found`      | Resource does not exist    |
| 500         | `internal_error` | Internal server error      |

## Summary

ORBEXA provides a comprehensive API endpoint system covering the three major protocols (UCP/ACP/MCP), OTR trust queries, three platform integrations, and discovery endpoints. The rate limiting system applies tiered policies by endpoint type to ensure fair usage and platform stability.

***

Next chapter: [Merchant Dashboard](/en/book-7/ch9-dashboard) -- KPI monitoring, integration management, data quality, and team permissions