701 - An automation that answers a request

• 701An automation that answers a requestWhat an endpoint is, the request a handler is handed and the answer it returns, who binds it, the limits a request runs under, and what a caller is told.
• 702A lookup a partner system callsThe three access modes, API keys and per-caller limits, one audit row per request, refusals by reason, signed tokens, and the Endpoints page.
• 703Your first formA form the agent writes: fields, live choices, field-by-field refusals, the checks the platform runs first, the hosted page, and submissions as a table.
• 704Putting the form on your site, or in a reportEmbedding in an asset and on an allowed site, named bot checks, the honeypot, and the minimum fill time.
• 705Sensitive fieldsEncryption before storage, who reads in clear and where, audited reads, exports, and why a file field cannot be sensitive.
• 706From submission to actionAn automation that runs once per submission, validation against live data, bursts and failures, and writes to other systems.
• 707Capstone: the supplier form end to endThe demo tenant’s supplier program assembled: form, page, table, intake automation, and a report joining applications to the warehouse.

An automation

An endpoint is a managed script like any in the 600 series: written by the agent, saved with tests, versioned, and run under the access its author held at the save. What makes it an endpoint is one function, handle(req), and a binding to an address.

An address

/endpoints/<name>

Each binding has a name unique across the deployment. A request to that address runs the handler on the server that received it and answers with what the handler returns.

A lookup or feed

The answer is data: JSON computed from the warehouse, the catalog, an API connection, or anything else the automation may reach. Every answer is served as an opaque document that runs no script, and is not cached unless the handler says so.

Not web hosting

An endpoint does not serve a website or an application. It answers requests with data, one at a time, inside fixed limits. A page people fill in is a form, the subject of 703.

method

The HTTP method: GET, POST, PUT, PATCH, DELETE, or HEAD.

path

The path the caller sent.

params

Values from the binding’s path template. A template of /{sku} hands the segment over as params["sku"].

query

The first value of each query parameter, such as query["state"].

headers

The request headers with names in lower case. The caller’s credentials (Authorization, Cookie, X-API-Key) are left out.

body, json, form

The body as bytes, parsed as JSON when it says it is JSON, and as fields when it is a URL-encoded form. A body that claims to be JSON and is not is refused before the handler runs.

caller

Who the platform found the caller to be, on an endpoint that requires sign-in or a key: their id, email, and whether they used a session or an API key. It never comes from the request body. Lesson 702 covers the access modes.

def handle(req):
    """Lists the active ACME stores in one state, for the store finder on acme.example.com."""
    state = req["query"].get("state", "").upper()
    if state not in STATES:
        return {"status": 400, "json": {"error": "state must be a two-letter US state code"}}
    rows = platform.query(
        "SELECT s.store_id, s.store_name, s.address, s.city, s.state, s.zip_code, s.phone, " +
        "r.region_name AS region FROM warehouse.public.stores s " +
        "JOIN warehouse.public.regions r ON r.region_id = s.region_id " +
        "WHERE s.is_active AND s.state = :state ORDER BY s.city, s.store_id",
        params = {"state": state},
        connection = "acme",
    )
    return {
        "headers": {"Cache-Control": "public, max-age=300"},
        "json": {"state": state, "count": len(rows["rows"]), "stores": rows["rows"]},
    }

→ manage_script
  {
    "command": "endpoint_set",
    "name": "acme-store-finder",
    "endpoint": "store-finder",
    "methods": ["GET"],
    "auth_mode": "bot_check",
    "bot_check": "default",
    "allowed_origins": ["https://www.example.com"],
    "rate_limit": 300,
    "timeout_seconds": 10
  }

← {
    "endpoint": "store-finder",
    "enabled": true,
    "url": "https://mcp-demo.plexara.io/endpoints/store-finder",
    "max_body_bytes": 1048576,
    "max_memory_bytes": 67108864,
    "caller_rate_limit": 120,
    "message": "acme-store-finder now answers GET at
                https://mcp-demo.plexara.io/endpoints/store-finder."
  }

endpoint

The name in the address. Lowercase letters, digits, hyphens, and underscores, unique across the deployment.

methods, path

The methods answered (GET unless set) and an optional template under the name, such as /{sku}.

auth_mode

Who may call: authenticated, public, or bot_check. Required, with no default. Lesson 702.

timeout_seconds

10, at most 60

How long one request may run before the caller is answered 504.

max_body_bytes

1 MiB, at most 10 MiB

The largest body accepted. A larger one is answered 413 and the handler never runs.

rate_limit

600 a minute

Requests a minute the endpoint takes on each server. Past it, a caller is answered 429 with a time to retry.

allowed_origins

Websites whose browsers may call the endpoint directly from a page. Empty answers no cross-origin request.

GET /endpoints/store-finder?state=il
X-Bot-Check: <the answer to the store finder's challenge>

200 OK
Cache-Control: public, max-age=300
Content-Security-Policy: default-src 'none'; sandbox

{
  "state": "IL",
  "count": 12,
  "stores": [
    { "store_id": 103, "store_name": "ACME Store #103", "address": "1202 Park Dr",
      "city": "Arlington", "state": "IL", "zip_code": "96952",
      "phone": "(926) 696-6809", "region": "Midwest" },
    { "store_id": 96, "store_name": "ACME Store #96", "address": "5141 Main Rd",
      "city": "Ashland", "state": "IL", "zip_code": "45629",
      "phone": "(965) 820-6941", "region": "Midwest" },
    ... ten more
  ]
}

400

from the handler

Whatever the handler decides. The store finder answers 400 with a message for an unknown state.

404

No enabled endpoint has the name, or the path does not match the template.

405

The method is not one the endpoint answers; the answer lists the ones it does.

413

The body is larger than the binding allows. The handler does not run.

429

Past the endpoint’s rate, or the caller’s own rate on an authenticated endpoint, with a time to retry.

500

The handler failed, or returned something that is not an answer.

503

The automation is disabled or superseded, the handler held too much memory, or the server is already running its share of handlers.

504

The handler ran past its timeout.

default time per request, at most 60

10 s

memory one request may hold

64 MiB

default body, at most 10 MiB

1 MiB

handlers running at once on each server

32

1. 1

   Draft with a request built by hand

   A draft runs main(), so the agent writes a main() that calls handle with the request a caller would send. The draft runs for real and records every platform call and its answer.

2. 2

   Test against the recording

   A test replays that recording and asserts on the answer: the store finder’s tests check that Illinois returns 12 stores in the Midwest and that ZZ is answered 400.

3. 3

   Save, and the tests run

   A save runs the tests as it does for any automation and is refused while one fails or a branch is never reached.

4. 4

   Every request runs the newest version

   The first request after a save runs the new version on every server. There is no separate deploy step.