Choosing a Poly resource

Use this page to pick the right catalog type. It is a decision guide, not a full how-to. After you pick, follow the linked chapter.

Start here

Work the questions in order. You can need more than one resource (for example an API Endpoint plus a server function plus a Trigger).

  1. Call a third-party HTTP API with templated URL, auth, and args? Train an API Function.

  2. Expose a public HTTP URL that the world can POST or GET? Create an API Endpoint, then a Trigger to a server function.

  3. Run on a cron, interval, or one-shot time? Create a Job that invokes a server function.

  4. Consume a GraphQL provider subscription? Create a GraphQL Subscription that invokes a server function (args are [event, params]).

  5. Host your own logic on Poly (webhook/job/GraphQL target, logs, callable from any SDK language)? Deploy a server function.

  6. Small same-language helper, not its own FaaS unit? Deploy a client function.

  7. Share source for humans to copy (JSON, markdown, or code), not a callable? Store a snippet.

  8. Wrap an LLM with a prompt, typed args, and optional tools? Create an AI Function.

Callable code

Need

Prefer

Why

Templated outbound HTTP to a third party

API Function

Gateway runs the trained method, URL, headers, and body

Hosted logic, webhook/job/GraphQL target, logs

Server Function

Knative FaaS; POST /functions/server/:id/execute

Same-language helper shared by a server function or local SDK

Client Function

Runs in-process; not billed as its own server execution

Call from another language’s SDK

API or Server Function

Client functions are same-language only

Vari .inject() inside the body

Server Function (or an API Function path)

Client code cannot resolve inject

Source for people to copy, not poly.…()

Snippet

Not a runtime function

LLM prompt + optional tool functions

AI Function

Separate execute meter; v2 /functions/ai

 
$ npx poly function add helloWorld ./hello-world.ts --context myContext --server
$ npx poly function add sharedHelper ./shared-helper.ts --context utils --client
$ npx poly snippet add mySnippet ./my-snippet.ts --context best.snippets

Expose, schedule, subscribe

Need

Prefer

Why

Public HTTP URL

API Endpoint (Webhook Handle)

Gateway ingress. Canopy/REST still say Webhooks

Run a server function when that URL is hit

Trigger (webhook source)

Optional Wait for Response (one per webhook)

Run a server function on a schedule

Job

Same three Event args as webhook Triggers

Run a server function when another function fails

Trigger (error-handler source)

Payload is one error object, not Event args

Run a server function on GraphQL provider events

GraphQL Subscription

Args are [event, params]

Outbound call to a third party

API Function

Not an Endpoint. No inbound URL

Webhook and Job server functions use:

function handler(eventPayload, headersPayload, paramsPayload) {
    // …
}

Python handlers must accept those three arguments (or *args). See Events and Triggers.

Endpoint vs API Function

These names collide. They are opposite directions.

API Endpoint (Webhook Handle)

API Function

Direction

Inbound (world → Poly)

Outbound (Poly → third party)

Primary use

Expose a URL; Triggers; static ACK

Train and proxy an external API

Do not

Call this an “API Function”

Expect a public inbound URL

Data and config

Secrets and small config: Vari. Thousands of structured rows: Tabi. Existing warehouse or system of record: API Function or a driver in a server function.

Visibility still applies (ENVIRONMENT / TENANT / PUBLIC). Execute and manage are different permissions. Client functions have no execute route. Visibility, API Key Permissions.