builds

Build a tool

Build a new tool for a task on a website and return its job.

  • A build runs your example once. The tool is reused after that.
  • A build's build.eta gives how long builds like it usually take.
  • Follow the job with GET /v1/jobs/{id} or job webhooks.
  • If an existing tool already covers the task, the job names it as tool_id and build.existing_tool_id.
  • Ticket, bank, government and link shortener sites are refused with site_not_supported.
post/v1/builds

Request

  • Base URL: https://api.pomerado.ai
  • URL: https://api.pomerado.ai/v1/builds
  • 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

taskstring required

What the tool should do, in plain words

site_urlstring

The website's https origin, which every build needs; a path is dropped, so use start_url for a page

start_urlstring

An https page on site_url that the user gave, which the build opens unchanged as its start page, path, query and fragment kept

effect'read' | 'write' | 'ask'

read if the tool only looks things up; write if it changes the website (submits, books, saves a form, uploads, updates an account); ask to have the build work it out from the task, asking first only when the task is unclear. Required for a website build.

login_idstring

a saved login ID: login_ and 32 lowercase hex digits

save_loginboolean

Save login for later runs (requires login)

force_sign_inboolean

true: sign in before the example even if the task might work signed out, so the tool always signs in. Needs site_url. Otherwise a read build tries signed out and signs in (with login_id, login or the site's saved login) only when the task needs an account or hits a sign-in wall; the tool then needs a login only if the build signed in. A write or ask build given login_id or login always signs in first.

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 tool's builds, changes and runs coming from: US, GB, FR, DE or SG. Without it, a new tool uses the US and a change keeps the tool's location. 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.