List the piece catalog
The catalog of pieces (integrations) the worker fleet can currently run — the vocabulary every workflow definition is written in.
SIZE WARNING, READ THIS FIRST. The default response is the FULL catalog with every action and trigger schema inlined: measured at 206,735 bytes for the 50 shipped pieces (~59,000 tokens). ?view=index returns the same 50 pieces as one-line entries — measured at 9,784 bytes (~2,800 tokens), a 21x reduction — carrying id, name, description, category, version, versions, actionIds, triggerIds, needsConnection. That is everything needed to CHOOSE a piece. Fetch the index first, then fetch the one operation you actually need from GET /api/pieces/{id}/actions/{actionId}. Only fetch the default view if you genuinely need every schema at once.
?view= accepts exactly one value, index. A non-empty value that is not index is refused with 400 VALIDATION_ERROR (a mistyped ?view=indx used to silently serve the 206 KB default). An EMPTY ?view= and any unrecognised query key are ignored and serve the default full catalog.
q and category are read ONLY when view=index; on the default view they are ignored and the full catalog is returned unchanged.
CACHING. Unfiltered responses carry an ETag of the form "<fingerprint>-<source>" (the index view appends -index, so the two views never share a validator) plus Cache-Control: no-cache. Send it back as If-None-Match to get a 304. FILTERED responses (q or category supplied) carry NO ETag and can never 304.
PROVENANCE. Every response carries X-GoRunner-Catalog-Source. fleet means live workers published this and flows can run. last-known or compiled mean NO worker is checked in: pieces can still be browsed and flows edited, but nothing can execute. See GET /api/pieces/catalog-status.
Authorization
bearerAuth An API token: Authorization: Bearer grt_…. Mint one in the app under Settings → Workspace → API tokens; the raw value is shown once. Scopes confine the token — see x-permission on each operation.
In: header
Query Parameters
Projection to return. Omit (or send empty) for the full 206 KB catalog. index returns the 9.8 KB one-line-per-piece projection — use this unless you need schemas. Any other non-empty value is a 400.
Value in
- "index"
Free-text filter, applied ONLY when view=index. Case-insensitive substring match against the piece's id, name and description concatenated. Ignored (not an error) on the default view.
Exact, case-insensitive category match, applied ONLY when view=index. Categories in the shipped 50-piece build: Data (29), Logic (11), Triggers (6), Communication (2), HTTP (2). Ignored on the default view.
Header Parameters
An ETag previously returned by this endpoint FOR THE SAME VIEW. Matches if the header contains the current ETag as a substring, so a comma-separated list works. A match returns 304 with no body.
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/api/pieces?view=index&q=http&category=Logic" \ -H "If-None-Match: "7abf423b2cf0e9d918f30e4a8878984f-fleet-index""{ "data": [ { "id": "string", "name": "string", "description": "string", "logoUrl": "string", "version": "string", "versions": [ "string" ], "icon": "string", "category": "string", "nodeType": "action", "kind": "core", "actions": [ { "id": "string", "name": "string", "description": "string", "sideEffects": "pure", "inputSchema": { "type": "string", "properties": { "property1": { "type": "string", "title": "string", "description": "string", "default": null, "enum": [ "string" ], "enumLabels": { "property1": "string", "property2": "string" }, "format": "string", "properties": { "property1": {}, "property2": {} }, "items": {}, "propertyType": "string", "placeholder": "string", "group": "string", "order": 0, "required": true, "minLength": 0, "maxLength": 0, "min": 0, "max": 0, "pattern": "string", "refreshers": [ "string" ], "refreshOnSearch": true, "expressionEnabled": true, "language": "string", "displayConditions": [ { "field": "string", "operator": "eq", "value": null, "values": [ null ] } ] }, "property2": { "type": "string", "title": "string", "description": "string", "default": null, "enum": [ "string" ], "enumLabels": { "property1": "string", "property2": "string" }, "format": "string", "properties": { "property1": {}, "property2": {} }, "items": {}, "propertyType": "string", "placeholder": "string", "group": "string", "order": 0, "required": true, "minLength": 0, "maxLength": 0, "min": 0, "max": 0, "pattern": "string", "refreshers": [ "string" ], "refreshOnSearch": true, "expressionEnabled": true, "language": "string", "displayConditions": [ { "field": "string", "operator": "eq", "value": null, "values": [ null ] } ] } }, "required": [ "string" ] }, "outputSchema": { "type": "string", "properties": { "property1": { "type": "string", "title": "string", "description": "string", "default": null, "enum": [ "string" ], "enumLabels": { "property1": "string", "property2": "string" }, "format": "string", "properties": { "property1": {}, "property2": {} }, "items": {}, "propertyType": "string", "placeholder": "string", "group": "string", "order": 0, "required": true, "minLength": 0, "maxLength": 0, "min": 0, "max": 0, "pattern": "string", "refreshers": [ "string" ], "refreshOnSearch": true, "expressionEnabled": true, "language": "string", "displayConditions": [ { "field": "string", "operator": "eq", "value": null, "values": [ null ] } ] }, "property2": { "type": "string", "title": "string", "description": "string", "default": null, "enum": [ "string" ], "enumLabels": { "property1": "string", "property2": "string" }, "format": "string", "properties": { "property1": {}, "property2": {} }, "items": {}, "propertyType": "string", "placeholder": "string", "group": "string", "order": 0, "required": true, "minLength": 0, "maxLength": 0, "min": 0, "max": 0, "pattern": "string", "refreshers": [ "string" ], "refreshOnSearch": true, "expressionEnabled": true, "language": "string", "displayConditions": [ { "field": "string", "operator": "eq", "value": null, "values": [ null ] } ] } }, "required": [ "string" ] }, "sampleData": {}, "errorHandling": { "retryOnFailure": true, "maxRetries": 0, "continueOnFailure": true }, "timeoutSeconds": 0 } ], "triggers": [ { "id": "string", "name": "string", "description": "string", "type": "webhook", "inputSchema": { "type": "string", "properties": { "property1": { "type": "string", "title": "string", "description": "string", "default": null, "enum": [ "string" ], "enumLabels": { "property1": "string", "property2": "string" }, "format": "string", "properties": { "property1": {}, "property2": {} }, "items": {}, "propertyType": "string", "placeholder": "string", "group": "string", "order": 0, "required": true, "minLength": 0, "maxLength": 0, "min": 0, "max": 0, "pattern": "string", "refreshers": [ "string" ], "refreshOnSearch": true, "expressionEnabled": true, "language": "string", "displayConditions": [ { "field": "string", "operator": "eq", "value": null, "values": [ null ] } ] }, "property2": { "type": "string", "title": "string", "description": "string", "default": null, "enum": [ "string" ], "enumLabels": { "property1": "string", "property2": "string" }, "format": "string", "properties": { "property1": {}, "property2": {} }, "items": {}, "propertyType": "string", "placeholder": "string", "group": "string", "order": 0, "required": true, "minLength": 0, "maxLength": 0, "min": 0, "max": 0, "pattern": "string", "refreshers": [ "string" ], "refreshOnSearch": true, "expressionEnabled": true, "language": "string", "displayConditions": [ { "field": "string", "operator": "eq", "value": null, "values": [ null ] } ] } }, "required": [ "string" ] }, "outputSchema": { "type": "string", "properties": { "property1": { "type": "string", "title": "string", "description": "string", "default": null, "enum": [ "string" ], "enumLabels": { "property1": "string", "property2": "string" }, "format": "string", "properties": { "property1": {}, "property2": {} }, "items": {}, "propertyType": "string", "placeholder": "string", "group": "string", "order": 0, "required": true, "minLength": 0, "maxLength": 0, "min": 0, "max": 0, "pattern": "string", "refreshers": [ "string" ], "refreshOnSearch": true, "expressionEnabled": true, "language": "string", "displayConditions": [ { "field": "string", "operator": "eq", "value": null, "values": [ null ] } ] }, "property2": { "type": "string", "title": "string", "description": "string", "default": null, "enum": [ "string" ], "enumLabels": { "property1": "string", "property2": "string" }, "format": "string", "properties": { "property1": {}, "property2": {} }, "items": {}, "propertyType": "string", "placeholder": "string", "group": "string", "order": 0, "required": true, "minLength": 0, "maxLength": 0, "min": 0, "max": 0, "pattern": "string", "refreshers": [ "string" ], "refreshOnSearch": true, "expressionEnabled": true, "language": "string", "displayConditions": [ { "field": "string", "operator": "eq", "value": null, "values": [ null ] } ] } }, "required": [ "string" ] }, "sampleData": {}, "derivesSample": true } ], "auth": { "type": "none", "required": true, "description": "string", "fields": [ { "name": "string", "title": "string", "type": "string", "required": true, "description": "string" } ], "oauth2": { "authorizationUrl": "string", "tokenUrl": "string", "scopes": [ "string" ], "scopeSep": "string", "authParams": { "property1": "string", "property2": "string" } } }, "actionsByVersion": { "property1": [ "string" ], "property2": [ "string" ] }, "triggersByVersion": { "property1": [ "string" ], "property2": [ "string" ] } } ]}