runs

Run a tool

Run a website tool once and return its job.

  • Follow the job with GET /v1/jobs/{id} or job webhooks until it finishes or needs input. Retry-After suggests when to read it again.
  • A tool that signs in uses the site's saved login, and login_id picks one when there are several. login is used only when no login is saved.
  • Runs on one saved login go one at a time.
  • Send an Idempotency-Key with every write. A retry with the same key returns the same job instead of acting on the website again.
  • A result over 256 KiB comes as result_file, a single-use result.json download, with result_preview showing its start, and result is null. A result over 32 MiB fails the run with result_too_large.
post/v1/runs

Request

  • Base URL: https://api.pomerado.ai
  • URL: https://api.pomerado.ai/v1/runs
  • Auth: HTTP bearer

Headers

Idempotency-Keystring

1 to 200 letters, digits, _ or -, such as a UUID

Repeat a request safely: the same key and body answer the first request's job again with Idempotent-Replayed: true; the same key with a different body answers idempotency_conflict.

Request body

tool_idstring required

The ID of the tool to run, from a tool search

login_idstring

a saved login ID: login_ and 32 lowercase hex digits

save_loginboolean

Save login for later runs (requires login)

two_factor_method'sms' | 'call' | 'email' | 'authenticator' | 'push'

The two-factor method to use when the site offers several; one the tool supports

correct_logintrue

Fix the rejected saved login named by login_id during this run

redact_at_restboolean

Staging and preview only: true seals what this job stores and redacts it once it settles, false keeps it readable, overriding the environment's setting. Production refuses a request that names it with invalid_request.

location'US' | 'GB' | 'FR' | 'DE' | 'SG'

The country websites see this run coming from: US, GB, FR, DE or SG. Without it, the run uses the tool's location, which this doesn't change. Private tools on Business accounts only.

proxystring

Your own proxy for this call, as http://username:password@host:port, in place of Pomerado's. Leave out location when you pass it. Pomerado keeps it only until this call and any repair it starts have ended. Private tools on Business accounts only.

Example request

{
  "login_id": "login_0f8e2d1c4b3a49e8a7f6e5d4c3b2a190"
}

Response

The job this Idempotency-Key already started, with Idempotent-Replayed: true

idstring required

a job ID: job_ and 32 lowercase hex digits

type'run' | 'build' required
status'queued' | 'running' | 'needs_input' | 'succeeded' | 'failed' | 'cancelled' required
tool_idstring nullable required
resultunknown required
result_previewunknown
result_status'available' | 'delivered' | 'expired' nullable required
result_expires_atstring required

a string to be decoded into a Date

write_status'not_attempted' | 'may_have_applied' | 'applied' | 'not_applied' nullable required
messagestring nullable required
site_urlstring nullable

The website's https origin the job was asked for: a build's site_url, or the site of the tool a run runs

site_namestring nullable

The site's name: its tool's integration's, else the integration of its website; null until one names it

taskstring nullable

A build's task, or a requested change, as it was sent; null for a run and a job accepted before Pomerado kept tasks

tool_namestring nullable

The name of the tool tool_id names, as GET /v1/tools shows it

waiting_sincestring nullable

When the question input_request asks was asked; null when the job asks none

watch_urlstring required
tipstring
created_atstring required

a string to be decoded into a Date

updated_atstring required

a string to be decoded into a Date

completed_atstring required

a string to be decoded into a Date

Example response

{
  "id": "job_0f8e2d1c4b3a49e8a7f6e5d4c3b2a190",
  "input_request": {
    "id": "req_0f8e2d1c4b3a49e8a7f6e5d4c3b2a190"
  },
  "build": {
    "integration_id": "int_0f8e2d1c4b3a49e8a7f6e5d4c3b2a190"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.