Services & Actions

A service is a third-party API that Overslash knows how to talk to (GitHub, Gmail, Slack, …), described by a YAML file in the service registry. An action is a named, parameterised operation on that service (github.create_issue, gmail.send_message, …). Agents call actions by name; Overslash resolves them to authenticated HTTP requests at execution time.

The service registry

A service starts life as a template: an OpenAPI 3.1 document, annotated with a handful of x-overslash-* vendor extensions, that declares the API's base URL, how it authenticates, and which operations are exposed as actions. Templates are loaded into an in-memory service registry at startup — every .yaml/.yml file under the registry directory is parsed, validated, and keyed by its service key (github, gmail, google_calendar, …). A file that fails to parse or validate is skipped with a logged error rather than taking the process down, so one broken template never blocks the rest.

It helps to keep two words straight:

• A template is the definition — the YAML. It says how to talk to an API but carries no credentials of its own.
• A service instance is a template plus bound credentials, scoped to an org (and optionally shadowed per-user). Calling github resolves to your GitHub instance, with your connection or secret attached.

The registry also injects one synthetic entry that has no YAML file: the http pseudo-service, which exposes raw HTTP calls for APIs that don't have a template yet. Granting http is rare — it effectively turns Overslash into a general-purpose HTTP proxy — and most orgs leave it ungranted. See Permissions for how the http and secret pseudo-services are gated.

Action types: read vs. write

Each operation in a template has an operationId (the action name) and a risk level — read, write, or delete. Risk is either declared explicitly or inferred from the HTTP method (GET/HEAD/OPTIONS → read, POST/PUT/PATCH → write, DELETE → delete).

Risk is not cosmetic. It maps directly onto the coarse-grained access levels a group can grant — read access permits read actions, write adds mutating actions, and admin adds destructive ones — so the same risk value that documents an action also determines who is allowed to call it. A service grant marked auto_approve_reads lets an agent run read actions with no approval at all, while writes always flow through the approval path. Both behaviours are described in Permissions and Approvals.

Parameters and templating

Actions take parameters — path segments, query strings, and request bodies — declared in the usual OpenAPI way and validated against the template's schema before a call goes out. Three Overslash extensions shape how those parameters surface elsewhere:

• scope_param names the parameter that becomes the :arg segment of the permission key. For a calendar action with scope_param: calendarId, a call against one calendar produces the key google_calendar:create_event:<calendarId>, so a grant can be scoped to a single calendar rather than the whole service.
• resolve turns an opaque identifier into a human-readable name for display — given a calendarId, Overslash can fetch the calendar and pick its summary, so approvals and audit rows read "Work" instead of a random ID.
• Summary templating lets an action declare a sentence like "Create event '{summary}' on calendar {calendarId}", interpolated with the resolved parameters so a human reviewing an approval sees exactly what is about to happen.

Custom services

The registry ships with templates for common APIs, but it isn't closed. Org admins (and template authors) can add new templates or import an existing OpenAPI document, and agents can create service instances programmatically — by default on_behalf_of their owner-user, so the resulting instance lands in that user's namespace rather than the agent's. Templates are validated on registration and again on promotion, so a malformed disclose filter or auth block is rejected before it can reach a live call.

See also: Reference → Service registry for the full YAML schema, and Permissions for how a call is authorized once an action resolves.