Capabilities

A capability is something your pod can do: send an email from your account, search the web, publish a post, run a piece of code you wrote. Your agents, automations, apps and scripts ask the pod to do it; the pod runs it, with the credential it holds, under your governance.

What a capability is made ofCopy Anchor Link

A capability is a connection to one service plus the verbs that use it. A verb is one action with named inputs, such as gmail_send or calendar_list. Installing a capability creates its parts in your pod, in this order:

A capability can also ask questions when you install it (for example "Your API key") and bring playbooks and automations that use its verbs.

A verb's ID is its name: that is what you pass to run it.

See what your pod hasCopy Anchor Link

• Pod admin console: Tools lists everything installed on the pod (capabilities, instructions and code), and each row opens that tool's own page. Marketplace lists what you can install. Both are for the pod's owner and admins.

• CLI:

  Copy Text

  synap capability list              # one row per capability: status, connection, verbs
  synap capability show <name>       # one capability in detail, with the next thing to do

• Your agent: synap_list_capabilities returns your connected services, each with its verbs and whether it is connected, plus standalone runnable skills. A verb that is installed but switched off is marked blocked: "not_enabled", with a link for you to turn it on.

• API: GET /api/hub/capabilities with a key that has the hub-protocol.read scope. See Capabilities in the Hub REST API.

Install oneCopy Anchor Link

Capabilities come from the marketplace. From the CLI:

# pick one from the catalog
synap capability add
# or name it; it asks for anything it needs, such as an API key
synap capability add <name>
# sign in to the service, or give its credential
synap capability connect <name>
# turn it on and choose which verbs it may run
synap capability enable <name>

A capability that is installed but not turned on cannot run: every run is refused until you enable it. A capability can hold several accounts for one service (synap capability connections list <name>); a run uses the default one unless it names another.

Your agent can install one too (ask it, for example, "find a capability for my calendar and propose installing it"). An agent's install is always a proposal (a Request in the apps) that you approve.

From the API, POST /api/hub/capabilities/apply installs a catalog capability by its templateKey with its params, and needs the hub-protocol.write scope. When a person still has to answer a question or connect an account, it answers with what is missing (missingFields, or the connection to make).

Run a verbCopy Anchor Link

curl -X POST https://pod.example.com/api/hub/capabilities/execute \
  -H "Authorization: Bearer $SYNAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "verbId": "<verb name>", "parameters": { "query": "…" } }'

The body takes verbId (or skillId), parameters, and optionally workspaceId, connectionSelector (which account to use) and idempotencyKey (so a retried send happens once). The key needs the hub-protocol.write scope. The answer is 200 with the result, or 202 with status: "proposed", a proposalId and a reviewUrl when the run waits for your approval.

What governance appliesCopy Anchor Link

• You run your own capability directly. A person running a capability they own is not asked.
• An agent's run is checked. A read-only verb runs. Any other verb runs when you granted it to that agent or a rule allows it; otherwise the run becomes a proposal you approve, and the agent gets status: "proposed" with a reviewUrl. This is a success, not an error. Running a verb is decided by these grants, not by the agent's write mode; records the verb writes back into your pod follow the write mode like any other agent write.
• "Never" holds. When you set a rule that says never for an agent and a kind of action, its run is refused.
• Untrusted origin asks you. A run started from an outside channel becomes a proposal even when it would otherwise run.
• A changed verb is switched off. When what an approved verb runs changes (its code, the hosts it may reach, a tool it uses), it is turned off until a person approves it again. Applying a marketplace update you chose keeps it on.

See Validation policy for the rules every write follows.

Make your ownCopy Anchor Link

From the smallest change to the largest:

1. A new verb on a service you already connected, with no code: ask your agent to add it. synap_create_verb describes one HTTP call on an installed tool (method, pathTemplate, query, body, responseShape, parameters), and the pod runs it. It cannot run code, and it cannot create a new connection.

2. A verb that runs code, when one HTTP call is not enough: a code skill. See Run your own code.

3. A whole capability: write a definition as JSON with at least a key, a name, its tools and its skills (and optionally params, vault, provides, playbooks and automations), then install it on your pod:

   Copy Text

   synap capability create ./my-capability.json
   synap capability enable "<its name>"

   synap capability create sends the definition to POST /api/hub/capabilities/apply. Parts that need your approval come back as proposals.

4. Share it: publish it to the marketplace as a capability package. See Publish your own.

RelatedCopy Anchor Link

• Marketplace
• Automations and playbooks
• Run your own code
• API keys