# Your first Agent API call in five minutes

The COD PRO Agent API is one HTTPS endpoint. Your agent sends a scoped key as a Bearer token and names a tool, such as order_summary or wallet_summary, with its arguments. COD PRO works out which store the key belongs to and answers in JSON.

- Endpoint: POST /api/agent/v1/call
- Authentication: Authorization Bearer header with your Agent API key
- Request body: A tool name plus its arguments, as JSON
- Rate limit: 60 requests a minute per key

## Make the call

```bash
curl -X POST https://codpro.khaalti.app/api/agent/v1/call \
  -H "Authorization: Bearer $CODPRO_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tool": "order_summary", "arguments": {"order_id": "1042"}}'
```

## Tools and the scope each one needs

| Tool | Scope | What it does |
|---|---|---|
| capabilities | none | Lists what this key may and may not do |
| order_summary | read:orders | One order and its confirmation state |
| order_messages | read:orders | Messages sent for an order |
| recent_events | read:orders | Recent confirmations, cancellations and replies |
| customer_profile | read:customers | A customer's history across orders |
| order_stats | read:stats | Confirmation and order statistics for a period |
| wallet_summary | read:wallet | Wallet balance and recent usage |
| configuration_summary | read:configuration | Your current COD PRO settings |
| precheckout_status | read:configuration | Pre-checkout verification settings |
| trigger_verification_send | send:otp | Sends the confirmation for an order (uses wallet credit) |
| order_decision | write:orders | Marks an order confirmed or cancelled |
| release_hold | write:orders | Releases an order hold |
| update_settings | write:configuration | Changes COD PRO settings |
| update_precheckout | write:configuration | Changes pre-checkout verification settings |
| set_app_paused | control:pause | Pauses or resumes COD PRO |

## Good habits

Give each agent its own key with only the scopes it needs, keep keys out of prompts and front-end code, and revoke a key from COD PRO the moment you stop using it.

## What it costs

API calls themselves are not charged. Tools that send messages use your wallet at the normal per-country prices on the [pricing page](/pricing).

## FAQ

### How do I authenticate to the COD PRO Agent API?
Create an Agent API key in COD PRO, then send it in the Authorization header as "Bearer" followed by the key. The key decides which store and which tools the request can reach.

### What does a request look like?
A POST with a JSON body holding "tool" and "arguments", for example {"tool": "order_summary", "arguments": {"order_id": "1042"}}.

### How do I find out what my key is allowed to do?
Call the capabilities tool. It returns the tools your key is granted and the ones it is not.

### What happens if my agent sends too many requests?
Each key can make 60 requests a minute. Tools that send messages have a tighter spend limit and answer with HTTP 429 and a plain message when you need to wait.

### Can my agent pass a different store in the request?
No. The store always comes from the key itself, never from the request, so a key can only ever act on its own store.

Last updated: 2026-09-26

Canonical: https://codpro.app/developers/api-quickstart