ARCY AI
SettingsInstall

Endpoints

Register the operations a Request step or the chat agent performs, say how a write answers, which numbers are amounts and which Event a success reports.

An endpoint is one operation of your product that a flow can perform. Register it on Settings > Install > Endpoints; a Request step on Flows picks one.

How it runs is Route, an HTTP call, or Handler, a function your page registers with registerHandler; the rest of the row is the same either way. Use a Handler where there is no route: a Server Action, a tRPC procedure, a GraphQL mutation.

Before you start

  • Only an admin can change the catalogue. Members see the list.
  • A Route calling another Site needs that Site's Domain verified on Domains. A Handler needs none.
  • The call carries the visitor's cookies. For a bearer token, set requestHeaders on Reference.

Setting it up

Add endpoint opens the dialog: the identity on top, then eight closed rows, Inputs, Body, Response fields, How it answers, Marks, In chat, Before it runs and What visitors read, one open at a time.

  • Name is what a Request step lists; renaming it breaks nothing.
  • How it runs. A Route takes Method, GET, POST, PUT, PATCH or DELETE, and Base address, blank for the page's own Site or https://api.acme.com under a verified Domain. A Handler takes Handler name: lowercase letters, digits and underscores, starting with a letter, used once in the Product. Changing it needs a matching change in your code.
  • How it answers, one line for each way an operation can answer: Done, Needs visitor, Pending and Refused. A line takes A named field equals with a Field path and a Value, A named field is one of with up to four Values, comma separated, or A named field holds a value; Done reads 2xx status until declared and also takes A 2xx status is enough, and Refused on a Handler takes The function threw. Needs visitor names a Link field, Refused a Reason field, both response fields the operation declares. Lines left empty: a 2xx means done and any other status is a no, and a Handler must say how it is refused. Where lines overlap, Refused wins, then Needs visitor, Pending, Done. Declare a field only where a 200 can mean something else, such as {"kind": "declined"}.
  • Changes data, under Marks on a Handler: on when performing it writes something.
  • Path follows the fixed /. Insert attribute drops in an input, {{ lead_id }}, or a visitor attribute, {{ user.plan }}. A flow answer reaches the path only through an input bound on the step. A placeholder before the ? must name a Required input. A placeholder in the query may name an optional input; when the run holds no value the whole key=value pair is left out.
  • Inputs, up to 50: a Name, a Type (Text, Number, Datetime or True or false) and Required.
  • No undo for an operation that deletes, cancels, sends or books something. A separate mark from Changes data: an operation can save something and still be undoable.
  • Ends on another page for an operation whose success moves the visitor, such as one that redirects. It declares no response fields, and the flow carries on where the visitor lands. The line you read holds the line in your code it came from.
  • Body template, for a Route on POST, PUT and PATCH: JSON where an input goes bare, {"email": {{ email }}}, and an attribute in quotes, {"plan": "{{ user.plan }}"}. A Handler takes none: it receives the inputs as one object.
  • Response fields, up to 20, read from the JSON answer into the run: a Name, What it holds and a Path in response. The path is dotted, data.id, and a list item is its index, data.0.email. A leading $ and bracket indexes are rewritten when you save; a path that still reads nothing is refused with the reason.
  • What it holds is Text, Number, Datetime, True/false, List, Object, Object list or Masked. Point the path at the whole collection, data.slots, where a flow or a chat needs every item. A List holds up to 50 words, an Object list up to 50 records. A Masked value prints as •••• and its last four.
  • Is this an amount of money? on every Number input and Number response field. Not an amount for a count or a rating. An amount, always in one currency takes its ISO 4217 code. An amount, currency named by a field takes a text field of the same operation carrying the code. Both take How the value is sent: whole units, hundredths, thousandths or ten-thousandths, so a price your API sends as 180000 reads as ₺1.800. A number nobody has answered for is marked on the table and prints exactly as your API sends it.
  • Visible to, on each response field: AI and dashboard, AI only, Dashboard only or Neither. Hidden from the AI, a value is dropped in your browser before anything leaves the page. Hidden from the dashboard, the trail your team reads shows the field's name as Masked while the agent still uses it (Conversations).

Names are lowercase letters, digits and underscores, starting with a letter, each used once; user and answers are reserved.

Rules on an input's row sets what a value must be. A Text input takes Shortest length, Longest length, a Shape, a Pattern and Allowed values. Shape is Email, URL, Phone number, UUID, CUID, Slug, Date (YYYY-MM-DD) or IPv4 address. Pattern is a regular expression the whole value must match, for a shape the list cannot say: write it alone, no slashes and no flags, up to 200 characters, and it may not repeat a group that already repeats inside itself. A Number input takes Lowest value, Highest value, Whole numbers only and Allowed values. Datetime and True or false take none. Allowed values holds up to 20 values of up to 100 characters, and each must fit the input's other rules.

In chat sets what the chat agent may do with the operation; flows are unaffected. Use in chat is on by default; Use when, Pin in chat, Needs sign-in, Run without asking and Open after show only while it is on, and saving needs Use when: one sentence, up to 200 characters, saying when to reach for the operation. Needs sign-in marks an operation only a signed-in visitor can perform; the agent does every other step first, then links to your sign-up page. Reports Event names the Event a success means; ARCY records it whenever it performs the operation and the answer reads as done, so never also send it from a handler ARCY runs. Run without asking, off by default, drops the approval question (How AI request content is handled). It appears only on an operation that changes data and is not marked No undo. Open after is the path on your site where the result lives, /orders/{{ response.id }}, with placeholders over the inputs and the response fields; Button label, up to 40 characters, is the button the chat draws under its answer to open it. Both or neither. Pin in chat keeps the operation among the agent's tools when a Product has more than it can hold at once. Before it runs, on an operation that writes, names up to three attributes ARCY must hold first and the question it asks for each (Persona).

What visitors read holds the words a visitor meets, one tab per language your Product serves: Step label on the running step, Open after button, and a label and a question for each input. The question a visitor reads before a write runs and the sentence they read when it succeeded belong to the Procedure that calls the operation, not to the row. Write them in ARCY's voice, sentence case, never calling the reader a visitor. A row missing a language is marked, and that reader meets ARCY's neutral words until it is written; a proposal from your agent missing one is refused. Shows as draws a read's result as Side by side, Grid of photos, List or Nothing, from a List field, Title field, Photo field, Link field and up to six labelled rows.

Lookup on an input's row says how ARCY finds a record, so a visitor is never asked for an id. Set it on an input that is a record, such as a path parameter app_id. Three sources, tried in order: From an attribute, an Attribute that holds the id; From the page, a route pattern with the input's name in braces as one whole segment, /{app_id}/production/flows; From an operation, a read of this catalogue whose records carry it, with Records field (its Object list field), Id field and Name field as the keys inside each record, and Example record, one real record of that list as JSON whose keys hold both; or an empty Records field and two response fields when it answers one record. Refused: an operation that changes data, this endpoint itself, a field it does not answer, an example record missing a key, a pattern without the input. A Lookup your agent declared searchable reads "searched with" and the input: ARCY performs the read with the visitor's words, so a record past the first page is found by name; otherwise the pick covers a short list. In the chat, the record the visitor stands on is used without asking and named on the approval question; several are names on pills, up to eight, then a typed name; typing a pill's name presses it. An input named id, or ending in _id or Id, is never asked of a visitor even without a Lookup. Name a record's own name after its noun, flow_name: a bare name or email is filled from the visitor's profile.

Reach carries the method on a route and Handler on a handler. Effects shows Changes data, No undo and Ends on another page, only where they are set. In chat, Needs sign-in and Runs without asking show those facts; In chat says why one is not offered, reads By search on an operation the agent finds by name rather than holds, and adds Pinned beside Offered on one you pinned. Target is the path or the handler name. Written by names your agent's token or the person who saved the row.

Seen on a page says where arcy.js has found a handler registered live, and reads Not seen yet until your deploy goes out. A flow using that handler still publishes; the canvas and the Publish dialog on Flows warn and name the environments.

Import an API description reads what you have, up to 2 MB: an OpenAPI 3 or Swagger 2 document, a Postman collection, a HAR export of your own traffic, a GraphQL introspection result, or a route listing from your agent. ARCY names the format it read. Tick the routes; Base address comes from the file's server. Path and required query parameters and the body's first-level scalar properties become inputs, the first success response's properties become response fields, and minLength, maxLength, minimum, maximum, type: integer, enum and format email or uri become Rules. A route with the same method and path is updated, name kept. Nothing is deleted. A HAR export is read as shapes: Authorization, Cookie, Set-Cookie, any secret-named field and every captured value are left out before anything is stored, and the dialog names what went. GraphQL arrives as one route per query and mutation, arguments as variables.

Hand it to your agent opens ARCY MCP, and Ask your developer beside it gives you a link to send instead. Proposals show here under Proposed by your agent: Accept all or Reject all at the top, Accept or Reject on each row. Destructive marks a route that deletes or cancels for good, kept on Accept, and a row may carry the agent's note.

A proposal naming an endpoint you already have arrives as a change, not a second row. It lists what it would change, field by field, and names every published flow whose step reads what is changing. Accept rewrites that endpoint in place. When two operations' inputs carry the same meaning, a row says they are asked once and names them, so you catch a wrong link first.

A row reading Removes an endpoint is one your agent found no code behind, with its reason. Remove deletes the endpoint and is refused while a flow uses it; Keep leaves it, and no agent proposes removing it again until you edit it.

Test in a row's menu asks for each input and attribute the endpoint reads, and a Site when it calls the page's own, then sends it from your browser with your session, never through ARCY, and shows the HTTP status, time and every response field. A value that breaks a rule is not sent. Unavailable on a Handler: preview the flow on Flows instead.

Tick rows, or every row shown with the header box; Shift-click ticks a range. The bar above the table holds Clear, a menu each for Use in chat, Needs sign-in and Run without asking with Turn on and Turn off, and Delete. Each entry says how many rows it reaches and which it skips: Delete keeps an endpoint a flow uses, and turning Run without asking on skips a No undo row and one that changes no data. Those two confirm first; the rest apply at once and Written by names you.

What it changes

  • A Request step performs the operation from the visitor's browser with their session. Only the outcome and HTTP status reach the analytics on Flows. The assistant may perform it too: what reaches a model.
  • The How it answers lines are read in one order, before any response field is stored and before the step's event is reported. A matching Refused fails the step, Needs visitor and Pending leave it waiting, and only Done succeeds. The visitor gets one card for each: the reason, a button to the link, a line saying it is waiting, or the Procedure's result sentence. A failed or waiting operation sets no run variable and counts nothing, and its declared fields still reach the words the agent may say.
  • A response field the answer leaves out or sends as null stays unset, and the step goes on.
  • A required input whose value breaks a rule, or cannot be read as its type, is never sent: the step reports a failed Step result and your failure branch runs. An optional one is left out and the call goes.
  • An operation that changes data asks the Procedure's approval question first, with Yes, do it and Not now only, and a second one asks again. Each row takes the input's label; an id prints as the record's Name field from its Lookup, a declared amount in the visitor's own currency format, a date in their own time zone, and an id it cannot name is left off; a required priced read adds its amount.
  • What a visitor gives is kept for the whole conversation, whichever operation asks: inputs sharing a meaning are asked once, the dates and counts carry to the next record of the same kind, and a change replaces only its own value. It ends with the conversation, and with Store conversations off nothing is kept past the turn. A write still prints every value on its approval card first.
  • An operation marked No undo, one that bills, or one with an effect outside your site is explained and offered rather than performed, whatever the visitor asked for, and nothing is staged until they accept.
  • A required value ARCY cannot find in the visitor's own messages, in a read earlier in the same turn, or in the operation's own defaults or allowed list is asked for, never filled in. A declared amount is asked in whole units with a stepper, and the call still carries the number your API takes.
  • A read that answers with a declared amount and changes no data is a priced read. Once a turn, with no step drawn, ARCY performs one itself as soon as the turn holds every input it needs, and the agent is told it may never add amounts up or name a figure it did not read.
  • Editing an endpoint, re-importing it, or accepting a change to it reaches every published flow at once, with no republish; a flow whose step reads something that moved needs a review before its next publish. Used by names the flows calling it; Delete is refused while any does.
  • History in the editor of a saved operation lists its changes, and Restore puts a version back, as on Procedures. Deleting the operation deletes its history.

When it goes wrong

Delete is disabled. The menu lists the flows still calling it; in the bar, every ticked row is in use. Remove their step first.

HTTP 401 on a test call. Your API refused the cookie session; the dialog shows the requestHeaders snippet to add.

A test call did not reach the server. Allow this dashboard's domain in your API's CORS rules, with credentials.

A test call says a field is not in the response. Fine where it does not apply; otherwise the path does not match your JSON.

A Request step fails on a response field. Your API answered with a different type from the one the field declares. Change What it holds, or the path, to match it.

A step says it is not usable. Its handler is not registered on the page the visitor is on. Check the deploy went out and that Handler name matches your registerHandler call. On a route, no verified Domain covers its base address any more; verify it again.

A step waits, then apologises for something that worked. The operation redirects and its Ends on another page is off. Switch it on.

Import fails. The file is not valid JSON or YAML, is Swagger 2.0, or has no paths.

See also

On this page