Owlbound
Browse the docs

Reference · 7 operations

Actions: catalog and runs

Every capability as one operation actions.<family>.<verb>: one target model, dry run, lifecycle and audit (the catalog is GET /action-types).

Last updated from API version 2026-10-06 at (live spec, refreshed hourly). openapi.json

Action types

actionTypes.list

The action catalog: every actions.* operation.

get/api/v1/action-types
Scope
read
Credits
Free
Idempotency-Key
Not used

Operation id, summary, safety class, input JSON schema, accepted target kinds, sync support, price, approval floor and the rate-limit bucket it spends. Generated from this document, so the CLI, MCP and docs read one source. Filter with class. Not paginated (one entry per operation).

Parameters

  • classquerystring

    Safety class: decides scope, approval, caps and enforcement.

    readwritespendexternal_writesend

Responses

200
Every action operation, sorted by id.
Show schema

ActionTypeListResponse

Errors

400 The request is invalid (VALIDATION_ERROR, CURSOR_MISMATCH, UNSUPPORTED_FILTER) · 401 Missing, invalid, expired or revoked key · 403 Missing scope, suspended workspace or unavailable identity · 429 Rate limit reached · 500 Unexpected error · 503 The backend is unreachable; retry after `Retry-After`. Every error is {error: {type, code, message, requestId, docUrl}}; see error codes.

curl "https://app.owlbound.ai/api/v1/action-types" \
  -H "Authorization: Bearer $OWLBOUND_API_KEY" \
  -H "Owlbound-Version: 2026-10-06"

actionTypes.get

One action operation of the catalog.

get/api/v1/action-types/{operationId}
Scope
read
Credits
Free
Idempotency-Key
Not used

Parameters

  • operationIdpathstringrequired

    An action operation id, e.g. actions.find.provider_id.

Responses

200
The operation.
Show schema

ActionTypeResponse

  • dataActionTyperequired

    One action operation, from this document's x-owlbound-action.

    0
  • metaResponseMetarequired

    Metadata on every success response.

    0

Errors

400 The request is invalid (VALIDATION_ERROR, CURSOR_MISMATCH, UNSUPPORTED_FILTER) · 401 Missing, invalid, expired or revoked key · 403 Missing scope, suspended workspace or unavailable identity · 404 Unknown resource or route. A resource in another workspace is also 404 · 429 Rate limit reached · 500 Unexpected error · 503 The backend is unreachable; retry after `Retry-After`. Every error is {error: {type, code, message, requestId, docUrl}}; see error codes.

curl "https://app.owlbound.ai/api/v1/action-types/$OPERATION_ID" \
  -H "Authorization: Bearer $OWLBOUND_API_KEY" \
  -H "Owlbound-Version: 2026-10-06"

Action runs

actionRuns.list

List the workspace's actions, newest first.

get/api/v1/actions
Scope
read
Credits
Free
Idempotency-Key
Not used

Every action run in the workspace, by any key, session or agent. Filters: kind (an operation id), status, createdAfter (milliseconds since the epoch). tableId is reserved. Cursor-paginated.

Parameters

  • limitqueryinteger

    Page size.

    default 50min 1max 200
  • cursorquerystring

    Opaque cursor from meta.page.nextCursor. Reusing it with other filters is 400 CURSOR_MISMATCH.

  • kindquerystring
  • statusquerystring
    pending_approvalqueuedrunningsucceededfailedrejectedcanceledexpiredpartial
  • tableIdquerystring

    Reserved: any value is 400 UNSUPPORTED_FILTER until table targets ship.

  • createdAfterqueryinteger

Responses

200
One page of actions.
Show schema

ActionListResponse

Errors

400 The request is invalid (VALIDATION_ERROR, CURSOR_MISMATCH, UNSUPPORTED_FILTER) · 401 Missing, invalid, expired or revoked key · 403 Missing scope, suspended workspace or unavailable identity · 429 Rate limit reached · 500 Unexpected error · 503 The backend is unreachable; retry after `Retry-After`. Every error is {error: {type, code, message, requestId, docUrl}}; see error codes.

curl "https://app.owlbound.ai/api/v1/actions" \
  -H "Authorization: Bearer $OWLBOUND_API_KEY" \
  -H "Owlbound-Version: 2026-10-06"

actionRuns.get

Get one action, optionally waiting for it to finish.

get/api/v1/actions/{id}
Scope
read
Credits
Free
Idempotency-Key
Not used

waitSeconds (0 to 30) holds the request until the action reaches a terminal status or the time is up, whichever comes first; poll again for longer waits. Without it the current state returns at once.

Parameters

  • idpathstringrequired

    The action id.

  • waitSecondsqueryinteger
    min 0max 30

Responses

200
The action.
Show schema

ActionResponse

  • dataobjectrequired
    0
    + Show child fields
    • actionActionrequired

      One action run. Read it again with GET /api/v1/actions/{id}.

      0
  • metaResponseMetarequired

    Metadata on every success response.

    0

Errors

400 The request is invalid (VALIDATION_ERROR, CURSOR_MISMATCH, UNSUPPORTED_FILTER) · 401 Missing, invalid, expired or revoked key · 403 Missing scope, suspended workspace or unavailable identity · 404 Unknown resource or route. A resource in another workspace is also 404 · 429 Rate limit reached · 500 Unexpected error · 503 The backend is unreachable; retry after `Retry-After`. Every error is {error: {type, code, message, requestId, docUrl}}; see error codes.

curl "https://app.owlbound.ai/api/v1/actions/$ID" \
  -H "Authorization: Bearer $OWLBOUND_API_KEY" \
  -H "Owlbound-Version: 2026-10-06"

actionRuns.cancel

Cancel an action's targets that have not started.

post/api/v1/actions/{id}/cancel
Scope
read
Credits
Free
Idempotency-Key
optional

Queued, scheduled and pending-approval targets become canceled; a running target finishes. Needs the scope of the action's class (read for a read action, enrich for a spend action). Idempotent: cancelling a finished action returns it unchanged. On an async run the open batches close (their credit holds are released, or settled for what already committed) and the action ends canceled shortly after.

Parameters

  • idpathstringrequired

    The action id.

  • Idempotency-Keyheaderstring

    1 to 255 printable ASCII characters, scoped to the API key (a rotated key shares its predecessor's keys) and kept 24 h. Accepted on every POST, PATCH and DELETE (ignored on GET); required from v1 keys where the operation says x-owlbound-idempotent: required (missing: 400 VALIDATION_ERROR, param: Idempotency-Key). Same key and body after completion: the stored response is replayed with Idempotent-Replayed: true. Results over 64 KB are not stored; their replay is 409 IDEMPOTENCY_RESULT_UNAVAILABLE with details.originalRequestId (check state with a GET). Same key while the first request runs: 409 IDEMPOTENCY_IN_PROGRESS with Retry-After. Same key, other body or operation: 422 IDEMPOTENCY_KEY_REUSED. A request that ended 5xx may be retried with the same key. 4xx results are stored and replayed too: a 402 INSUFFICIENT_CREDITS replays even after a top-up, so use a new Idempotency-Key after adding credits.

    min length 1max length 255

Responses

200
The action after the cancel.
Show schema

ActionResponse

  • dataobjectrequired
    0
    + Show child fields
    • actionActionrequired

      One action run. Read it again with GET /api/v1/actions/{id}.

      0
  • metaResponseMetarequired

    Metadata on every success response.

    0

Errors

400 The request is invalid (VALIDATION_ERROR, CURSOR_MISMATCH, UNSUPPORTED_FILTER) · 401 Missing, invalid, expired or revoked key · 403 Missing scope, suspended workspace or unavailable identity · 404 Unknown resource or route. A resource in another workspace is also 404 · 409 IDEMPOTENCY_IN_PROGRESS (the first request with this key is still running; `Retry-After` is the lease left, at most 60 s) or IDEMPOTENCY_RESULT_UNAVAILABLE (the original result was too large to store; `details.originalRequestId`). · 422 IDEMPOTENCY_KEY_REUSED (the key was used with another body or operation), or an action that cannot run · 429 Rate limit reached · 500 Unexpected error · 503 The backend is unreachable; retry after `Retry-After`. Every error is {error: {type, code, message, requestId, docUrl}}; see error codes.

curl -X POST "https://app.owlbound.ai/api/v1/actions/$ID/cancel" \
  -H "Authorization: Bearer $OWLBOUND_API_KEY" \
  -H "Owlbound-Version: 2026-10-06" \
  -H "Idempotency-Key: $(uuidgen)"

Targets

actionRuns.targets.list

The action's targets and their outcomes.

get/api/v1/actions/{id}/targets
Scope
read
Credits
Free
Idempotency-Key
Not used

One row per target: status, skip or failure reason, result. Filters status and reason. Cursor-paginated.

Parameters

  • idpathstringrequired

    The action id.

  • limitqueryinteger

    Page size.

    default 50min 1max 200
  • cursorquerystring

    Opaque cursor from meta.page.nextCursor. Reusing it with other filters is 400 CURSOR_MISMATCH.

  • statusquerystring
    queuedpending_approvalscheduledrunningsucceededskippedfailedcanceled
  • reasonquerystring

Responses

200
One page of targets.
Show schema

ActionTargetListResponse

Errors

400 The request is invalid (VALIDATION_ERROR, CURSOR_MISMATCH, UNSUPPORTED_FILTER) · 401 Missing, invalid, expired or revoked key · 403 Missing scope, suspended workspace or unavailable identity · 404 Unknown resource or route. A resource in another workspace is also 404 · 429 Rate limit reached · 500 Unexpected error · 503 The backend is unreachable; retry after `Retry-After`. Every error is {error: {type, code, message, requestId, docUrl}}; see error codes.

curl "https://app.owlbound.ai/api/v1/actions/$ID/targets" \
  -H "Authorization: Bearer $OWLBOUND_API_KEY" \
  -H "Owlbound-Version: 2026-10-06"

Audit

actionRuns.audit.list

The action's per-target audit trail, newest first.

get/api/v1/actions/{id}/audit
Scope
read
Credits
Free
Idempotency-Key
Not used

One row per target outcome: who acted (actor), the payload hash, the outcome and reason, the provider reference. Message bodies are never in the audit. Cursor-paginated.

Parameters

  • idpathstringrequired

    The action id.

  • limitqueryinteger

    Page size.

    default 50min 1max 200
  • cursorquerystring

    Opaque cursor from meta.page.nextCursor. Reusing it with other filters is 400 CURSOR_MISMATCH.

Responses

200
One page of audit rows.
Show schema

ActionAuditListResponse

Errors

400 The request is invalid (VALIDATION_ERROR, CURSOR_MISMATCH, UNSUPPORTED_FILTER) · 401 Missing, invalid, expired or revoked key · 403 Missing scope, suspended workspace or unavailable identity · 404 Unknown resource or route. A resource in another workspace is also 404 · 429 Rate limit reached · 500 Unexpected error · 503 The backend is unreachable; retry after `Retry-After`. Every error is {error: {type, code, message, requestId, docUrl}}; see error codes.

curl "https://app.owlbound.ai/api/v1/actions/$ID/audit" \
  -H "Authorization: Bearer $OWLBOUND_API_KEY" \
  -H "Owlbound-Version: 2026-10-06"

Models on this page

Shared objects the operations above link to. Clients must ignore fields they do not know.

ActionTypeobject

One action operation, from this document's x-owlbound-action.

  • operationIdstringrequired
    0
  • methodstringrequired
    0
  • pathstringrequired
    0
  • summarystringrequired
    0
  • descriptionstring | nullrequired
    0
  • classstringrequired

    Safety class: decides scope, approval, caps and enforcement.

    readwritespendexternal_writesend
  • scopestringrequired
    0
  • targetsarray of stringrequired
    contactcontactsrowsviewrecordsnone
  • syncbooleanrequired
    0
  • maxTargetsintegerrequired
    0
  • supportsDryRunbooleanrequired
    0
  • approvalstringrequired

    The floor; the key's approval mode can raise it.

    noneoptionalrequired
  • idempotentstringrequired
    requiredoptionalnone
  • priceobjectrequired
    0
    + Show child fields
    • capabilityIdstring | nullrequired
      0
    • perTargetobjectrequired
      0
      + Show child fields
      • minnumberrequired
        0
      • maxnumberrequired
        0
  • rateLimitobjectrequired
    0
    + Show child fields
    • weightintegerrequired
      0
    • sendBucketstring | nullrequired
      0
  • writesBackarray of stringrequired
    0
  • inputSchemaanyrequired

    JSON schema of the request's input.

    0
  • availablebooleanrequired

    False while the server does not run this class yet (the dry run still works).

    0
ResponseMetaobject

Metadata on every success response.

  • requestIdstringrequired
    0
  • creditsCreditsMetarequired
    0
  • pagePageMeta

    Cursor pagination. hasMore is the only end signal; pages may be short.

    0
  • dryRunboolean

    True only on a dry-run response (action operations).

    0
CreditsMetaobject
  • usednumberrequired

    Credits charged by this request. Reads are free.

    0
  • balancenumber
    0
  • estimatednumber

    Dry run only (action operations).

    0
  • availablenumber

    Dry run only (action operations).

    0
  • reservationIdstring | null

    Async operations only; the job settles this reservation.

    0
PageMetaobject

Cursor pagination. hasMore is the only end signal; pages may be short.

  • nextCursorstring | nullrequired
    0
  • hasMorebooleanrequired
    0
  • limitintegerrequired
    min 1max 200
Actionobject

One action run. Read it again with GET /api/v1/actions/{id}.

  • idstringrequired
    0
  • kindstringrequired

    The operation id.

    0
  • classstringrequired

    Safety class: decides scope, approval, caps and enforcement.

    readwritespendexternal_writesend
  • statusstringrequired
    pending_approvalqueuedrunningsucceededfailedrejectedcanceledexpiredpartial
  • identityIdstring | nullrequired
    0
  • approvalActionApproval | nullrequired
    0
  • costobjectrequired
    0
    + Show child fields
    • estimatednumberrequired
      0
    • chargednumberrequired
      0
    • reservationIdstring | nullrequired
      0
  • countsActionCountsrequired
    0
  • targetobjectrequired
    0
    + Show child fields
    • kindstringrequired
      0
    • tableIdstring
      0
    • viewIdstring
      0
    • columnIdstring

      The send column this action runs (tables.rows.push target column).

      0
  • outputobject | nullrequired
    0
  • resultanyrequired

    The single target's result (sync), or null; bulk results are per target.

    0
  • errorActionErrorrequired
    0
  • actorActionActorrequired

    Who started the action. agent is an LLM-driven caller (the in-app agent, MCP) acting for the key or member in onBehalfOf.

    0
  • createdAtnumberrequired
    0
  • updatedAtnumberrequired
    0
ActionApprovalobject
  • modestringrequired
    nonealwaysover_threshold
  • urlstring | nullrequired
    0
  • decidedBystring | nullrequired
    0
  • decidedAtnumber | nullrequired
    0
  • expiresAtnumber | nullrequired
    0
ActionCountsobject
  • totalintegerrequired
    0
  • queuedintegerrequired
    0
  • scheduledintegerrequired
    0
  • runningintegerrequired
    0
  • succeededintegerrequired
    0
  • skippedintegerrequired
    0
  • failedintegerrequired
    0
  • canceledintegerrequired
    0
ActionErrorobject
  • codestringrequired
    0
  • messagestringrequired
    0
ActionActorobject

Who started the action. agent is an LLM-driven caller (the in-app agent, MCP) acting for the key or member in onBehalfOf.

  • kindstringrequired
    apiKeysessionagentjob
  • idstringrequired

    API key id, user id, agent run id or job id.

    0
  • onBehalfOfobject

    Agent only.

    0
    + Show child fields
    • kindstringrequired
      apiKeysession
    • idstringrequired
      0
PagedResponseMetaobject

Metadata on a paginated success response.

  • requestIdstringrequired
    0
  • creditsCreditsMetarequired
    0
  • pagePageMetarequired

    Cursor pagination. hasMore is the only end signal; pages may be short.

    0
ActionTargetobject
  • idstringrequired
    0
  • actionIdstringrequired
    0
  • refobjectrequired
    0
    + Show child fields
    • contactIdstring
      0
    • rowIdstring
      0
    • recordIndexinteger
      0
    • pageinteger

      List actions only, the provider page.

      0
  • statusstringrequired
    queuedpending_approvalscheduledrunningsucceededskippedfailedcanceled
  • notBeforenumber | nullrequired
    0
  • reasonstring | nullrequired

    Skip or failure code, e.g. NO_LINKEDIN_URL, PROFILE_NOT_FOUND.

    0
  • resultanyrequired

    Operation-specific, e.g. {providerId, publicIdentifier, profileUrl, fullName}.

    0
  • creditsnumberrequired
    0
  • attemptsintegerrequired
    0
  • updatedAtnumberrequired
    0
ActionAuditEntryobject
  • idstringrequired
    0
  • actionIdstringrequired
    0
  • targetIdstringrequired
    0
  • operationIdstringrequired
    0
  • classstringrequired

    Safety class: decides scope, approval, caps and enforcement.

    readwritespendexternal_writesend
  • actorActionActorrequired

    Who started the action. agent is an LLM-driven caller (the in-app agent, MCP) acting for the key or member in onBehalfOf.

    0
  • identityIdstring | nullrequired
    0
  • payloadHashstringrequired

    SHA-256 of the canonical request input; message bodies are never stored here.

    0
  • outcomestringrequired
    succeededskippedfailedcanceledunknown
  • reasonstring | nullrequired
    0
  • providerstring | nullrequired
    0
  • providerRefstring | nullrequired
    0
  • creditsnumberrequired
    0
  • dryRunbooleanrequired
    0
  • requestIdstringrequired
    0
  • atnumberrequired
    0

← All operations