# Register an endpoint as an agent tool

> POST /custom-apis. HeyRik API parameters and documented request and response examples.

Source: https://www.heyrik.com/docs/api-reference/custom-apis/post-custom-apis-register-an-endpoint-as-an-agent-tool

POST https://server.heyrik.com/api/v1/custom-apis

## Headers

Authorization: Bearer $HEYRIK_API_KEY (required). Keep your key on your server.

## Parameters

- name (string, required): Tool name the agent calls, e.g. check_order_status.
- url (string, required): Your https endpoint.
- method (string): GET | POST | PUT | PATCH | DELETE. Default POST.
- headers (object): Sent on every call — put your own auth header here.
- description (string): Tells the agent WHEN to use it. Be specific.
- parameters (object): JSON-Schema of the arguments the agent should supply.

## Notes

The `description` is what the agent reasons over — a vague one means the tool fires at the wrong moment, or never.

## Request example

```sh
curl -X POST https://server.heyrik.com/api/v1/custom-apis \
  -H "Authorization: Bearer $HEYRIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "check_order_status",
    "url": "https://api.acme.com/orders/status",
    "method": "POST",
    "headers": { "X-Api-Key": "your-own-key" },
    "description": "Look up the delivery status of an order by its id.",
    "parameters": {
      "type": "object",
      "properties": { "order_id": { "type": "string", "description": "The order id" } },
      "required": ["order_id"]
    }
  }'
```

## Response example

```json
{
  "data": {
    "id": "capi_3f81",
    "name": "check_order_status",
    "url": "https://api.acme.com/orders/status",
    "method": "POST"
  }
}
```