tools

Request a change to a tool

Changed on

Request a change to an existing tool and return its job.

  • Ask for what the tool lacks, such as a filter, an input or an output field, instead of building another tool for the same site. Say the change in plain words.
  • A change takes about as long as a build. The tool keeps working meanwhile, and its callers get the change when it publishes. Follow the job with GET /v1/jobs/{id} or job webhooks.
  • example_input is the input of the one example the change runs, using any input the change adds. A write tool's change needs it and runs that example once for real.
  • Anyone who can run the tool and build tools can ask. A change from someone other than the tool's owner may only add or tighten what the tool returns, never remove or loosen it.
  • A change keeps every input working: it may add optional inputs, add allowed values or a default to one, or make a required one optional when the tool handles it missing.
  • One change per tool at a time from your account. Another while yours is under way answers change_pending.
post/v1/tools/{id}/changes

Request

  • Base URL: https://api.pomerado.ai
  • URL: https://api.pomerado.ai/v1/tools/{id}/changes
  • Auth: HTTP bearer

Path parameters

idstring required
Example:tool_0f8e2d1c4b3a49e8a7f6e5d4c3b2a190

a tool ID: tool_ and 32 lowercase hex digits

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

changestring

What the tool should do differently, in plain words

login_idstring

a saved login ID: login_ and 32 lowercase hex digits

save_loginboolean

Save login for later runs (requires login)

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' | 'paused' | '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

  • c07cea59691cRevision changes
    • warning

      added the new paused enum value to the response property for the response status

    • warning

      added the new paused enum value to the response property for the response status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status