# Custom API

> Connect your own website or system to your Mojeeb AI agent — the agent calls your API during a conversation to check order status, stock, bookings, or loyalty points and answers the customer with the result. Every paid plan.

Custom API lets your AI agent talk to your own system while it chats with a customer. You describe one request — a link, how to sign in, and when to use it — and the agent calls it when a customer asks, then answers in plain language. Typical uses: order status, stock and prices, booking confirmations, loyalty points. Custom API is included in every paid plan.

## How does the Custom API tool work?

You set up a tool once in the dashboard. From then on the agent uses it on its own: it recognizes a matching question, fills in the values from the chat, Mojeeb sends the request to your system, and the agent turns the reply into an answer. The customer only sees the answer, never the request or the raw reply.

The loop, step by step:

1. **A customer asks** — "Where is my order 1042?"
2. **The agent decides** — Your instruction says this tool is for order-status questions, so the agent picks it and takes `1042` as the order number.
3. **Mojeeb calls your system** — The request you configured is sent, for example `GET https://api.yourshop.com/orders/1042`, with your API key attached.
4. **Your system replies** — For example `{"status": "shipped", "eta": "2026-10-08"}`.
5. **The agent answers** — "Your order has shipped and should arrive on October 8."

Each tool is one request. If you want the agent to check orders and also look up products, create two tools.

## What can I connect?

Any system that answers over HTTPS with JSON replies: your online shop, a booking system, a CRM or ERP, or a backend your developer built. Nothing needs to be installed on your side — one existing endpoint is enough. Common examples:

- **Order tracking** — status, courier, delivery date, by order number
- **Products** — availability, price, sizes, and colors, by name or code
- **Bookings and appointments** — confirm, look up, or create a reservation
- **Customer accounts** — loyalty points, balance, or membership status
- **Internal systems** — any CRM, ERP, or custom backend with a web API

The system must be reachable from the internet. Private addresses, local networks, and `http://` links cannot be used.

## What do I need before I start?

You need a paid subscription, the HTTPS link of the request, the sign-in method your API expects, a sample value to test with, and replies in JSON. Whoever runs your system can supply the last four in a few minutes; nothing needs to be installed on their side. In detail:

1. A **paid** subscription (Starter or Professional) — see [Plans & Pricing](/docs/billing/plans-and-pricing)
2. The **link** of the request, starting with `https://`
3. The **sign-in method** your API expects — an API key, a bearer token, a username and password, or OAuth2 client credentials
4. A **sample value** to test with, such as a real order number
5. Replies in **JSON** — this is the only reply format the agent can read

## How do I create a Custom API tool?

Go to [Tools](https://dashboard.mojeeb.app/tools), pick the agent at the top of the dashboard, find **Custom API** under **Available tools**, and click **Connect**. The page **Connect your system** opens. Fill it in from top to bottom:

1. **Request** — Paste the link and choose the request type (GET, POST, PUT, PATCH, DELETE). Add extra headers only if your API needs them.
2. **Security** — Choose how the request signs in and paste the key or token. See [How does security work?](#how-does-security-work)
3. **Body** — Appears for POST, PUT, PATCH, and DELETE. Write the request body as JSON or as form fields.
4. **Inputs Mojeeb fills in** — Every `{{placeholder}}` you wrote in the link or body appears here. Describe each one so the agent knows what to put in it, and give a sample value for testing.
5. **Details** — Give the tool a name and write **When should Mojeeb use it?**
6. Click **Save & test**. Fix anything the test reports until it shows a reply.
7. When the test succeeds, the tool switches itself on — you see **Tool is on**. The **Turn on the tool** switch at the bottom of the page pauses it if you are not ready.

The tool now appears under **Active tools** on the Tools page.

![Mojeeb AI agent customer support - Custom API tool page with the Request and Security sections](/img/screenshots/mojeeb-ai-tools-custom-api-form-en.png)

### How do I write the link?

Write the link exactly as you would in a browser or in Postman, and put double curly braces around every part the agent should fill in from the chat. The start of the link, up to the first slash after the address (`https://api.yourshop.com`, with its port if it has one), is the domain and becomes the connection; the rest is the request Mojeeb sends each time:

```text
https://api.yourshop.com/orders/{{order_id}}
https://api.yourshop.com/products?search={{keyword}}&limit=3
```

Rules:

- The link must start with `https://` and point to a public address.
- Placeholders can go in the path or in the query, never in the domain.
- A placeholder name starts with a lowercase letter and uses only lowercase letters, digits, and underscores: `order_id`, `phone`, `keyword2`.
- A placeholder inside the path is always needed, so keep it **Required**. Only query placeholders may be optional.
- A query key whose placeholder is optional and left empty by the agent is dropped from the request, so `?order={{order}}&ref={{ref}}` works when the customer gives only one of the two.

### Which request types are supported?

GET, POST, PUT, PATCH, and DELETE. GET requests carry no body. Tools that change data in your system — usually POST or PUT — are set up the same way as read-only tools and can be turned on once they pass a test.

### How do I send a request body?

For POST, PUT, PATCH, and DELETE requests, a **Body** section appears below Security. Write the body once, with placeholders where the agent should insert values from the chat; everything else is sent exactly as written on every call. Two formats are available:

- **JSON** — Write the body as text and put placeholders in quotes, like any other value: `{"quantity": "{{qty}}"}`. When a placeholder is the whole value, Mojeeb sends the typed value, so a number arrives as a number and a boolean as a boolean. Anything without a placeholder is sent exactly as written, every time.
- **Form** — Flat key and value pairs, sent as a standard web form. No nested objects.

Example JSON body with one placeholder and fixed values:

```json
{
  "size": 3,
  "filters": [
    { "field": "active", "operator": "exact", "value": true },
    { "field": "name", "operator": "icontains", "value": "{{keyword}}" }
  ]
}
```

An optional placeholder the agent leaves empty is removed from the body rather than sent as empty text.

### How do I describe the inputs?

Inputs are detected automatically: every placeholder in your link or body becomes a row under **Inputs Mojeeb fills in**. The description you give is what the agent reads when deciding what to put there, so write it the way you would brief a new employee. For each input, fill in:

| Field | What it does |
|-------|--------------|
| **What goes here?** | The only explanation the agent gets, so be concrete: "The order number the customer is asking about, digits only" |
| **Type** | string, integer, number, boolean, or enum — a fixed list of allowed values that you type under **Options**, up to 20 |
| **Required** | If on, the agent must get the value from the customer before it can use the tool |
| **Format** | For string inputs only, an optional hint: Date, Date & time, Email, Phone number, or Link |
| **Sample value** | Used only for the test on this page; never sent to the agent |

![Mojeeb AI agent customer support - Inputs Mojeeb fills in and the Details section with the tool instruction](/img/screenshots/mojeeb-ai-tools-custom-api-inputs-en.png)

Type, Required, Format, and the enum list sit behind the **Options** link under each input; a new input starts as a required string. A tool can have up to 16 inputs. If the request has no placeholders, it is sent as-is every time — useful for fixed lookups such as "today's offers".

### How do I write "When should Mojeeb use it?"

This text is the agent's only guide for the tool, so write it as instructions to a new employee, up to 2,000 characters. Cover four things:

- **When to use it** — the customer questions that should trigger it, with examples
- **What the customer must provide** — and that the agent should ask for it first if missing
- **What the reply contains** — which fields matter and what they mean
- **What not to say** — fields the customer must never see, such as cost price or another person's phone number

Example:

```text
Use this tool when the customer asks about the status, location, or delivery date of an order
(for example: "where is my order?", "has it shipped?"). The customer must give the order number;
if they have not, ask for it first and do not call the tool. The reply contains "status",
"courier", and "eta". Tell the customer the status and the expected date in simple words.
Never mention the "warehouse_notes" field.
```

## How does security work?

Mojeeb sends the request to your system with your key exactly as you configured it — your system decides what the request is allowed to see. The key is stored once per domain and shared by every tool on that domain. Choose the method under **Security**:

| Authentication | What you enter | What Mojeeb sends |
|----------------|----------------|-------------------|
| **None** | Nothing | The request without credentials — only for public APIs |
| **API key** | Where to send it (header or query), the exact header or query name, the key, and an optional prefix | For example `X-API-Key: abc123` or `?api_key=abc123` |
| **Bearer token** | The token, the header name (default `Authorization`), and the prefix (default `Bearer`) | `Authorization: Bearer abc123` — change the prefix if your API expects another word, such as `Token` |
| **Basic (username & password)** | Username and password | A standard Basic authentication header |
| **OAuth2 (client credentials)** | Token URL, client ID, client secret, optional scope, and whether the credentials go in the body or in a Basic header | Mojeeb fetches an access token, reuses it until it is about to expire, then fetches a new one |
| **Custom headers** | Up to 8 headers; for each, the header name, a secret name, and the secret value | Each header exactly as named |

Keys and secrets are stored encrypted and are never shown again after you save; the page shows dots in their place. To replace one, choose **Replace it** under Security, enter the new key, click **Save & test**, and confirm **Change the key?**. The key belongs to the domain, so the new key applies to every tool on that domain. When you create a tool on a domain that already has a saved key, Mojeeb offers to reuse it with **Use it**.

What Mojeeb will not do:

- Send to `http://` links, private addresses, or local networks
- Follow redirects — the link you enter must answer directly
- Accept reserved headers such as `Host`, `Cookie`, or `X-Forwarded-For` — the form rejects them when you save

Put keys only in the **Security** section. A key typed into the link, the body, or an extra header is ordinary text: it is stored unencrypted and can appear in the tool log. Keys entered under Security never reach the log.

### What if my server needs a CSRF token?

Some servers, such as SAP Gateway and other OData services, refuse a POST, PUT, PATCH, or DELETE unless it carries a CSRF token fetched just before it. For those, open **Advanced** under **Security** and turn on **Server needs a CSRF token before writes (SAP, OData)**. Mojeeb then sends every write on that domain in two steps:

1. It asks your server for a token with a GET that carries `x-csrf-token: fetch`, the same authentication, and the headers and query values typed into the tool as they are, such as `sap-client=100`, so the token comes from the same system as the write.
2. It sends the write with the token and the session cookies your server returned with it.

- Reads (GET tools) never ask for a token.
- The setting belongs to the domain, like the key, so it applies to every write tool on that domain.
- By default Mojeeb asks for the token at the tool's own service root: the link's path up to its last slash, skipping back past any part that holds a placeholder, so `/ZCREATE_APPOINTMENT_SRV/APPOINTMENT` asks at `/ZCREATE_APPOINTMENT_SRV/`. The hint under **Fetch the token from (optional)** shows the path for the tool you're editing. To ask elsewhere on the same domain, enter a path there: it starts with `/` and has no query, no `..` and no placeholders.
- A value the agent fills in, a `{{placeholder}}`, isn't sent with the token request, so type `sap-client` into the link or a header as it is, for example `?sap-client=100`.
- Every write fetches a fresh token, and Mojeeb keeps no token or cookie between requests. Mojeeb waits up to 15 seconds for each of the two requests.
- You still can't type a `Cookie` header yourself: the cookies come from your server.

If a test says **Your site wants a CSRF token before writes**, click **Turn it on and test again**.

## How do I test a tool?

Click **Save & test**. Mojeeb saves the tool, sends one real request to your system (two for a write on a domain that needs a CSRF token) using the sample values you entered for the inputs, and shows the result. Every required input needs a sample value first; otherwise the panel says **Enter a sample value and test**.

- **Replied 200 in 350 ms** — Your system answered. Below it you see the request URL with the key masked, the request body if any, and the reply, pretty-printed and clamped to its first 40 lines with **Show all** to expand. For an oversized reply only a sample of its start is shown.
- The agent receives nothing from a test. It is for you only.

![Mojeeb AI agent customer support - Test panel of a Custom API tool showing the saved reply](/img/screenshots/mojeeb-ai-tools-custom-api-test-en.png)

Your company can run up to 30 tests per minute across all tools and team members. What the test messages mean:

| Message | What to check |
|---------|---------------|
| Your site couldn't find this page — check the link | The path is wrong, or the sample value does not exist in your system |
| Your site returned an error (500) | Your system failed; check its logs |
| Your site didn't reply in time | Mojeeb waited 15 seconds; make the endpoint faster |
| We can't reach this address — it must be public on the internet | The link points to a private or local address |
| We couldn't find this site — check the domain | The domain does not resolve |
| Your API works — but the reply is over 1 MB | Return less data, for example by paging |
| The reply isn't text or JSON | The endpoint returns a file or HTML instead of JSON |
| There's a problem with the site's security certificate | The HTTPS certificate is invalid or expired |
| Your site wants a CSRF token before writes (403) | Shown when your server's 403 reply mentions CSRF: it refuses writes without a token. Click **Turn it on and test again**, or turn it on under **Security** → **Advanced**; see [What if my server needs a CSRF token?](#what-if-my-server-needs-a-csrf-token) |
| Your site rejected the CSRF token Mojeeb fetched (403) | The token came from another place or system: check **Fetch the token from (optional)**, and type `sap-client` into the link or a header as it is |
| The server didn't hand out a CSRF token before the write | The token request failed or came back without a token; the line under the message gives the reason, such as `token fetch refused (HTTP 403)`. Check **Fetch the token from (optional)**, and that this login is allowed to fetch tokens |

## How do I turn a tool on or off?

A successful **Save & test** switches the tool on by itself — you see **Tool is on** — so a tool is never on without a green test behind it. To pause it, use the **Turn on the tool** switch at the bottom of the tool page, or open the three-dot menu (⋮) on its card under **Active tools** and use the **Active** switch. A paused tool keeps all its settings; the agent simply stops using it. It stays paused until you switch it on again or run the next **Save & test**.

Editing a tool clears its last test result. Run **Save & test** again after any change so you know the new version works. The tool does not turn itself off when you edit it, so test promptly.

## What does the AI see from the reply?

The agent receives the reply from your system as-is, up to 50,000 characters; anything longer is cut off at that point. It reads the field names and values to compose its answer, so three things make tools more reliable:

- **Return only what the customer may know.** Everything in the reply reaches the agent, including fields like cost price or internal notes. Remove them on your side, or name them in the instruction as fields never to mention.
- **Use clear field names.** `delivery_date` is understood; `dd` is guessed.
- **Keep replies small.** Three products with their details is a good size; a full catalog is not.

The agent is instructed never to paste raw JSON to the customer; it summarizes in the conversation's language.

If the request fails — a timeout, an error status, or an unreachable server — the agent is told that the call failed and why, and it decides how to answer, usually by apologizing and offering to pass the question to a person.

## How do I see what a tool did?

Every call the agent makes through a Custom API tool is recorded. On the Tools page, open the three-dot menu (⋮) on the tool card and choose **Log**. The **Execution history** page lists each call with its outcome, timing, and the exact request and reply, so you can see why the agent answered the way it did. It shows:

- **Total**, **Successful**, **Failed**, and **Avg time** at the top. Click Successful or Failed to filter the list.
- One entry per call with the time, status, and duration.
- **Request & response** — the exact request Mojeeb sent and the reply it received, useful when the agent gives an unexpected answer.
- **View Conversation** — opens the chat in which the agent used the tool.

![Mojeeb AI agent customer support - Execution history page of a Custom API tool with totals and recent calls](/img/screenshots/mojeeb-ai-tools-custom-api-log-en.png)

Keys are masked in the log. Values the agent filled in from the chat are shown in full.

## How do I edit or delete a tool?

Both actions live in the three-dot menu (⋮) on the tool card under **Active tools**. Editing reopens the setup page and clears the last test result; deleting removes the tool from the agent but keeps the saved connection for other tools on the same domain. The two options:

- **Edit** — Opens the same page you used to create it. Change the link, security, inputs, or instruction, then **Save & test**. The domain of the link cannot change; create a new tool for a different domain.
- **Delete** — Removes the tool from this agent after a confirmation. The same action is the trash icon, **Delete tool**, at the top of the tool page. The saved connection to your system stays, so other tools that use the same domain keep working.

## Common questions

### Can the agent create or change data in my system?

Yes. POST, PUT, PATCH, and DELETE tools work like read tools and can be turned on after a successful test. Because an AI agent can occasionally decide to call a tool twice — for example when a customer sends two messages in quick succession — make such endpoints safe to repeat, or have your system reject duplicates by order or reference number.

### Does Mojeeb retry a failed request?

No. Each decision by the agent produces exactly one request, or two for a write on a domain that needs a CSRF token (the token request, then the write), with no automatic retries and no redirects. If the request fails, the agent is told and answers accordingly, and the failure appears in the tool log.

### Does Custom API work with SAP?

Yes. SAP Gateway and other OData services work like any other API. If your server refuses writes without a CSRF token, turn on **Server needs a CSRF token before writes (SAP, OData)** under **Security** → **Advanced**, and type `sap-client` into the link or a header as it is; see [What if my server needs a CSRF token?](#what-if-my-server-needs-a-csrf-token).

### Can I use one tool for several endpoints?

No. A tool is one request to one link. Create one tool per question you want the agent to answer — for example "order status" and "product availability" as two tools on the same connection.

### Where do the requests come from?

From Mojeeb's cloud servers over HTTPS, not from the customer's device or the chat channel. Mojeeb does not publish a fixed list of IP addresses. If your API only accepts requests from allow-listed addresses, contact support before setting up the tool so the right addresses can be confirmed.

### Is my API key safe?

Keys are encrypted at rest, never displayed after saving, and sent only to the domain you configured. Keep keys out of the link and the body, where they would be stored as plain text in the tool log.

### Which plan includes Custom API?

Every paid plan: **Starter** and **Professional**. On the free plan the Custom API card on the Tools page shows a **Paid** badge and an **Upgrade** button instead of **Connect**; clicking it opens the plan options. See [Plans & Pricing](/docs/billing/plans-and-pricing).

### Can I set up tools from my own system?

Yes. The Public API adds, tests, switches on and reads the same tools, so an integration or an AI assistant can set them up for you; see [Custom API Tools](/docs/developers/agents/custom-api-tools) in the developer docs. The API key it needs comes with every paid plan.

### Can the agent look things up by the customer's phone number?

Only if the customer gives it in the chat. The agent fills inputs from what the customer writes; it does not have access to the channel's phone number or account details.

## Related

- [Agent Tools](/docs/tools/overview) — all tools at a glance
- [Plans & Pricing](/docs/billing/plans-and-pricing) — what each plan includes
- [Knowledge Base](/docs/features/knowledge-base) — teach the agent what the reply fields mean
- [AI Conversations](/docs/features/ai-conversations) — where tool answers appear