REST API
With REST API you turn any HTTP endpoint into a tool your agent can invoke during a conversation. Unlike MCPs (which connect a whole server), here you define a single request and tell the AI what data it must provide to run it.
Each API combines two things:
- A schema — the fields the AI must fill in (for example, an order ID).
- A complete HTTP request — method, URL, params, headers, body, and response options.
To start, click "Create API". The wizard has three steps: Identity → Define → Review and create. The API is created as a draft; you can enable it when it's ready.
Step 1: Identity
Give it a technical name and a description that let the AI know when to use the tool.
| Field | Description |
|---|---|
| Technical name | A unique identifier in the workspace. Only lowercase letters, digits, and underscores (_) are allowed. The AI sees the tool as api_<name> (for example, api_get_order_details). |
| Description | The text the AI reads to decide when to invoke the tool. Be specific: explain what it does and when to use it (for example: "Gets the full details of an order by its ID. Use it when the user asks about the status of a specific order."). Minimum 10 characters, maximum 1024. |
A good description is key: it's the only thing the AI uses to choose this tool among all the available ones. If you're not sure how to word it, use the "Autocomplete" button to generate a suggestion.
Step 2: Define the request
Here you build the actual HTTP call. Choose the method (GET, POST, etc.) and write the endpoint URL.
The request is organized into tabs:
| Tab | What it's for |
|---|---|
| Params | Query parameters appended to the URL (?key=value). Up to 25. |
| Authorization | How the request authenticates (token, API key, etc.). |
| Headers | Additional HTTP headers. |
| Body | The request body (for POST, PUT, etc.). |
| Settings | General options for the call. |
If you already have the call in cURL format, use "Import from cURL" to preload the method, URL, headers, and body automatically.
Variables
Variables are the dynamic part of the request. Type {{ }} in any field (URL, params, headers, or body) and a picker appears to insert one.
Context variables (ctx) — Data Platica knows about the conversation and fills in automatically. They appear in the picker with the CTX label:
| Variable | What it contains |
|---|---|
{{ctx.phoneNumber}} | Customer's phone number. |
{{ctx.workspaceId}} | Workspace ID. |
{{ctx.conversationId}} | Conversation ID. |
{{ctx.agentId}} | Active agent ID. |
{{ctx.agentName}} | Active agent name. |
{{ctx.channelId}} | Channel ID. |
Your own variables — If you type a name that doesn't exist (for example {{orderId}}), the picker offers "Create as new variable". Each variable appears in the Variables table, with these columns:
| Column | Description |
|---|---|
| Variable | The name you used inside {{ }}. |
| Mode | Where the value comes from (see below). |
| Type | The data type: string, number, integer, boolean, array, or object. |
| Description / Value | In AI mode, the description the AI reads to know what the field represents; in Fixed mode, the constant value. |
| Used in | Where the variable appears within the request (URL, query, header, or body). |
| Req. | Whether the field is required. |
The Mode defines where each variable's value comes from:
| Mode | Where the value comes from |
|---|---|
| AI | The AI fills in the value when invoking the tool. These variables make up the tool's schema. |
| Fixed | A constant value you define that never changes. |
| Context | Mapped to a piece of conversation data (a ctx value, like the customer's phone number). |
"View JSON Schema" opens the exact schema the LLM will see. It only includes variables in AI mode; Fixed and Context ones are preserved when saving but don't appear in the schema (they're constant or hidden from the AI). From that modal you can regenerate the schema from the variables or edit it by hand and click "Apply".
Step 3: Review and create
The final step shows a summary of the tool: name (tool name), method, URL, number of variables, and description.
From here you have two options:
- Create as draft — saves the API to keep editing it later. It stays inactive.
- Create and enable — creates the tool and makes it active right away.
Managing the API
After creating it, the API's detail view opens. If you saved it as a draft, it shows the DRAFT label and a "Publish" button to activate it (it takes you to this same view, now with the API active).
The detail view has several tabs:
| Tab | What it's for |
|---|---|
| Summary | General overview of the tool. |
| Editor | Edit the request and variables (same as Step 2). |
| Response | Define which part of the response the AI sees. |
| Advanced | Advanced tool options. |
| Logs | Log of API invocations. |
| Stats | Usage statistics. |
Summary tab
Shows and lets you edit the tool's identity (technical name and description, with "Autocomplete"), along with tracking metadata:
| Field | Description |
|---|---|
| Version | The tool's version number. |
| Last edited | Date and time of the last change. |
| Last tested | When it was last tested (— if never tested). |
Editor tab
It's the same builder as Step 2: there you edit the method, URL, tabs (Params, Authorization, Headers, Body, Settings), and the request variables. It also includes the "Test API" button.
Testing the API
From the Editor or the Response tab you can open "Test API" to run a real call without leaving Platica.
| Element | Description |
|---|---|
| Simulated input | The JSON the AI would pass as arguments when invoking the tool. Use "Auto-fill" to generate sample values. |
| Dry run | Simulates the call without actually sending it. |
| Run | Sends the request for real. |
After running, you'll see the result (success + response time) and the details of the sent request: method, final URL, headers, and authentication method.
Response tab
This is where you decide which part of your API's response the AI will see. Platica needs a real example for this: if you haven't tested the API yet, the tab will ask you to run "Test API" first; with the sample response in hand, you can map it.
Which part of the response does the AI use? — Pick a sub-path if the response carries more than you need. Platica suggests paths detected in the sample response (for example [0].name, [0].email) as one-click chips, or you can keep "Full response". Two side-by-side panels show the raw response and what the AI will receive, so you see the effect of every change instantly.
Filter fields — Limit which properties the AI sees within the selected path:
| Mode | What it does |
|---|---|
| All fields | The AI receives everything (default behavior). |
| Only these | The AI only sees the fields you check. |
| All except | The AI sees everything except the fields you exclude. |
Use it to cut noise (irrelevant fields that confuse the agent) or to hide sensitive data you don't want exposed to the AI.
Fail if the path doesn't exist — On by default. If you define a path and the API response no longer contains it, the AI receives a clear error instead of the full response. Turning it off can hide bugs (for example, the API changed its shape without notice); keeping it on is recommended.
Size limit — Cap on the characters the AI will see of the already-filtered JSON. If the response exceeds it, it's truncated with the [truncated …] marker so the AI knows data is missing. The default is 32,000 characters (≈ 8,000 tokens).
The more focused the response (a specific path + only the useful fields), the better and cheaper the agent's replies: fewer input tokens and less noise to interpret.
Advanced tab
Options for special cases, disabled by default:
Periodic auth — Automatically injects a token refreshed by a cron job of type auth. When you enable it, you configure:
| Field | Description |
|---|---|
| Cron job | The auth-type cron that generates the token. If you don't have one, create it first in Cron jobs and come back. |
| Inject into | Where the token is placed (for example, in a Header). |
| Name | The header name (for example, Authorization). |
| Prefix / Suffix | Text prepended or appended to the token (for example, the Bearer prefix). |
The "Value sent" field shows a preview of how the header with the token will look.
Encrypt payload (JWT) — Signs the request body with HS256 + exp and sends it as jdata form-urlencoded. Intended for specific legacy integrations. You configure the HS256 Secret and the token's TTL (seconds).
The Advanced options are for specific technical integrations. If you're not sure whether you need them, leave them off.
Logs tab
Records every API invocation (real and test calls) with its full history. At the top you'll see aggregate metrics: Total, Successes, Errors, Error rate, and P50 / P95 latencies (up to the last 30 days).
You can filter by All / Successes / Errors, search, and Export the log. Expanding a call shows its status, method, latency, and the full metadata (trigger, toolName, inputArgs, requestUrl, requestHeaders, sentBody) and, if it failed, the error message.
Stats tab
Summarizes the API's activity over a window of 24h, 7 days, or 30 days: number of calls, successes, errors (with their rate), and latency (p50 and p95).
Publishing, pausing, and managing
From the API's top bar you manage its state:
- Publish — activates the API (it leaves the draft state) so agents can use it.
- Pause — once published, you can pause it to temporarily disable it without deleting it.
- Menu (⋮) — from the three dots you can clone the API (to create a variant) or delete it entirely.