Skip to content
Blotout Docs

Call an app tool

POST
/teams/{teamId}/domains/{domainId}/apps/{appSlug}/tools/{toolName}
curl --request POST \
  --url https://qinto-api.blotout.io/teams/7b8d1a52-6c1e-4b6f-9a30-2f8a54d1c3e9/domains/3f2a9c81-5d47-4e0b-8c66-91b2a7f04d15/apps/facebook-capi/tools/emqReport \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "installId": "8d7c6b5a-4938-4271-a605-9e8f7a6b5c4d", "arguments": {} }'

Runs one of an installed app’s tools against a site and returns what the app answered. The arguments are validated against the schema the version that site actually serves declares, so a tool is always called on the contract in front of it.

How it works

The call runs as the caller, on the named site, in an app that site already installed. The caller’s app role on that site must reach the tool’s minimum role; an app they have no access to, or a tool above their role, answers not_found like one that does not exist. installId is required only where the app is installed more than once; install_required names the choices. A repeat is a new call: the platform neither retries nor deduplicates one. Every call is written to the team’s activity log, without its arguments. Requires an OAuth access token.

Required permissions

  • domain:read on all domains, or on the addressed domain when its id is in the route

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
teamId
required

Unique id (UUID) of the team that owns the addressed resources, as shown in the team settings on the Blotout platform.

string format: uuid

Example 

7b8d1a52-6c1e-4b6f-9a30-2f8a54d1c3e9

Unique id (UUID) of the team that owns the addressed resources, as shown in the team settings on the Blotout platform.

domainId
required

Unique id (UUID) of the site, as returned by the site operations.

string format: uuid

Example 

3f2a9c81-5d47-4e0b-8c66-91b2a7f04d15

Unique id (UUID) of the site, as returned by the site operations.

appSlug
required

Immutable slug of the app, as shown by the list operation.

string
/^[a-z][a-z0-9-]{2,29}$/

Example 

facebook-capi

Immutable slug of the app, as shown by the list operation.

toolName
required

The tool’s own name as the app’s manifest declares it, without the app-slug prefix.

string
/^[a-zA-Z][a-zA-Z0-9_]{0,31}$/

Example 

emqReport

The tool’s own name as the app’s manifest declares it, without the app-slug prefix.

Request Bodyrequired

Section titled “Request Bodyrequired”

Which installation to act on, and the tool’s own arguments.

Media typeapplication/json

Which installation to act on, and the tool’s own arguments.

object
installId

Which installation to run the tool against. Required only where the app is installed more than once.

string format: uuid

Example 

8d7c6b5a-4938-4271-a605-9e8f7a6b5c4d
arguments

The tool’s own arguments, validated against the schema its serving version declares.

object
key
additional properties

Example 

{}

Responses

Section titled “Responses”

200

Section titled “200”

What the tool answered.

Media typeapplication/json

What the tool answered.

object
outcome
required

How the call ended: ok the app answered, failed it declined and content is its own message, error the platform could not complete it.

string
Allowed values: ok failed error
content
required

The app’s answer, as text.

string
data

The app’s structured answer, when it returned one.

object
key
additional properties

Example 

{
  "outcome": "ok",
  "content": "Resent 12 events.",
  "data": {
    "sent": 12
  }
}

400

Section titled “400”

invalid_params — A path parameter failed validation (for example a malformed UUID); details pinpoints the offending parameter. invalid_body — The JSON body is unparseable or failed schema validation; details pinpoints the offending fields when the body could be parsed. invalid_arguments — The arguments do not match the schema the version this site serves declares; message names the offending property. Read the tool’s current schema before retrying.

Media typeapplication/json
object
error
required

Machine-readable error slug; switch on this value rather than on the HTTP status alone.

string
Allowed values: invalid_params invalid_body invalid_arguments
details

Field-level validation errors: a tree keyed by input property, each node carrying an errors array of human-readable messages. Render it to help the caller correct the request.

object
key
additional properties

Example 

{
  "error": "invalid_params",
  "details": {
    "errors": [],
    "properties": {
      "teamId": {
        "errors": [
          "Invalid UUID"
        ]
      }
    }
  }
}

401

Section titled “401”

unauthenticated — The Authorization: Bearer token is missing, malformed, or no longer valid. Generate a team API token or obtain a new OAuth access token.

Media typeapplication/json
object
error
required

Machine-readable error slug; switch on this value rather than on the HTTP status alone.

string
Allowed values: unauthenticated

Example 

{
  "error": "unauthenticated"
}

403

Section titled “403”

forbidden — The bearer credential lacks the required permission or belongs to another team, or its user lacks the organization role a developer operation needs. Update its policies, use a credential bound to the addressed team, or ask an organization owner for the role; message states the reason when one is known.

Media typeapplication/json
object
error
required

Machine-readable error slug; switch on this value rather than on the HTTP status alone.

string
Allowed values: forbidden
message

Human-readable reason for this specific failure, intended for display — do not parse it programmatically.

string

Example 

{
  "error": "forbidden",
  "message": "The Cloudflare API token is invalid or expired."
}

404

Section titled “404”

not_found — The addressed resource does not exist within this team; check the id and retry.

Media typeapplication/json
object
error
required

Machine-readable error slug; switch on this value rather than on the HTTP status alone.

string
Allowed values: not_found

Example 

{
  "error": "not_found"
}

409

Section titled “409”

not_deployed — The site has never been deployed, so it has no host to describe yet. Deploy it, then retry. tool_disabled — A site manager has switched this tool off for the site, so assistants may not call it there. Nothing ran. app_suspended — Blotout has suspended this app, so nothing ran and nothing changed. The call works again once the suspension is lifted. install_required — The app is installed more than once on this site, so the call must name which installation to act on; message lists them with their ids. install_inactive — The named installation is switched off, so nothing was dispatched to it. Turn it on, then retry.

Media typeapplication/json
object
error
required

Machine-readable error slug; switch on this value rather than on the HTTP status alone.

string
Allowed values: not_deployed tool_disabled app_suspended install_required install_inactive
message

Human-readable reason for this specific failure, intended for display — do not parse it programmatically.

string

Example 

{
  "error": "not_deployed",
  "message": "The Cloudflare API token is invalid or expired."
}

429

Section titled “429”

rate_limited — Too many requests for this API token or site in a short window; wait a minute and retry.

Media typeapplication/json
object
error
required

Machine-readable error slug; switch on this value rather than on the HTTP status alone.

string
Allowed values: rate_limited

Example 

{
  "error": "rate_limited"
}

500

Section titled “500”

internal — Unexpected server error. Nothing is guaranteed to have been persisted; idempotent operations are safe to retry.

Media typeapplication/json
object
error
required

Machine-readable error slug; switch on this value rather than on the HTTP status alone.

string
Allowed values: internal

Example 

{
  "error": "internal"
}