Request a change to a tool

curl --request POST \
  --url https://api.pomerado.ai/v1/tools/{id}/changes \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "change": "<string>",
  "example_input": {},
  "login_id": "login_0f8e2d1c4b3a49e8a7f6e5d4c3b2a190",
  "save_login": true,
  "redact_at_rest": true
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    change: '<string>',
    example_input: {},
    login_id: 'login_0f8e2d1c4b3a49e8a7f6e5d4c3b2a190',
    save_login: true,
    redact_at_rest: true
  })
};

fetch('https://api.pomerado.ai/v1/tools/{id}/changes', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.pomerado.ai/v1/tools/{id}/changes"

payload = {
    "change": "<string>",
    "example_input": {},
    "login_id": "login_0f8e2d1c4b3a49e8a7f6e5d4c3b2a190",
    "save_login": True,
    "redact_at_rest": True
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "id": "job_0f8e2d1c4b3a49e8a7f6e5d4c3b2a190",
  "type": "run",
  "status": "queued",
  "tool_id": "<string>",
  "input_request": {
    "id": "req_0f8e2d1c4b3a49e8a7f6e5d4c3b2a190",
    "expires_at": "<string>",
    "answer_url": "<string>",
    "message": "<string>",
    "questions": [
      {
        "id": "<string>",
        "prompt": "<string>",
        "type": "choice",
        "options": [
          {
            "id": "<string>",
            "label": "<string>"
          }
        ],
        "allow_other": true,
        "allow_note": true
      }
    ]
  },
  "result": "<unknown>",
  "result_status": "available",
  "result_expires_at": "<string>",
  "write_status": "not_attempted",
  "login_save": {
    "status": "saved",
    "login_id": "<string>",
    "reason": "<string>"
  },
  "error": {
    "error": {
      "code": "<string>",
      "message": "<string>",
      "retryable": true,
      "docs_url": "<string>",
      "details": {}
    }
  },
  "message": "<string>",
  "maintenance": {
    "status": "repairing",
    "result_recovered": true,
    "message": "<string>",
    "deadline_at": "<string>"
  },
  "build": {
    "integration_id": "int_0f8e2d1c4b3a49e8a7f6e5d4c3b2a190",
    "stage": "queued",
    "stages": [
      {
        "key": "queued",
        "label": "<string>",
        "status": "done",
        "started_at": "<string>",
        "completed_at": "<string>"
      }
    ],
    "eta": {
      "min_seconds": 123,
      "max_seconds": 123
    },
    "example_result": "<unknown>",
    "existing_tool_id": "<string>",
    "change": {
      "revision_id": "<string>",
      "previous_revision_id": "<string>",
      "write_started": true
    }
  },
  "watch_url": "<string>",
  "created_at": "<string>",
  "updated_at": "<string>",
  "completed_at": "<string>",
  "tip": "<string>"
}

{
  "id": "job_0f8e2d1c4b3a49e8a7f6e5d4c3b2a190",
  "type": "run",
  "status": "queued",
  "tool_id": "<string>",
  "input_request": {
    "id": "req_0f8e2d1c4b3a49e8a7f6e5d4c3b2a190",
    "expires_at": "<string>",
    "answer_url": "<string>",
    "message": "<string>",
    "questions": [
      {
        "id": "<string>",
        "prompt": "<string>",
        "type": "choice",
        "options": [
          {
            "id": "<string>",
            "label": "<string>"
          }
        ],
        "allow_other": true,
        "allow_note": true
      }
    ]
  },
  "result": "<unknown>",
  "result_status": "available",
  "result_expires_at": "<string>",
  "write_status": "not_attempted",
  "login_save": {
    "status": "saved",
    "login_id": "<string>",
    "reason": "<string>"
  },
  "error": {
    "error": {
      "code": "<string>",
      "message": "<string>",
      "retryable": true,
      "docs_url": "<string>",
      "details": {}
    }
  },
  "message": "<string>",
  "maintenance": {
    "status": "repairing",
    "result_recovered": true,
    "message": "<string>",
    "deadline_at": "<string>"
  },
  "build": {
    "integration_id": "int_0f8e2d1c4b3a49e8a7f6e5d4c3b2a190",
    "stage": "queued",
    "stages": [
      {
        "key": "queued",
        "label": "<string>",
        "status": "done",
        "started_at": "<string>",
        "completed_at": "<string>"
      }
    ],
    "eta": {
      "min_seconds": 123,
      "max_seconds": 123
    },
    "example_result": "<unknown>",
    "existing_tool_id": "<string>",
    "change": {
      "revision_id": "<string>",
      "previous_revision_id": "<string>",
      "write_started": true
    }
  },
  "watch_url": "<string>",
  "created_at": "<string>",
  "updated_at": "<string>",
  "completed_at": "<string>",
  "tip": "<string>"
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "docs_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "docs_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "docs_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "docs_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "docs_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "docs_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "docs_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "docs_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "docs_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "docs_url": "<string>",
    "details": {}
  }
}

POST

tools

{id}

changes

Request a change to a tool

curl --request POST \
  --url https://api.pomerado.ai/v1/tools/{id}/changes \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "change": "<string>",
  "example_input": {},
  "login_id": "login_0f8e2d1c4b3a49e8a7f6e5d4c3b2a190",
  "save_login": true,
  "redact_at_rest": true
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    change: '<string>',
    example_input: {},
    login_id: 'login_0f8e2d1c4b3a49e8a7f6e5d4c3b2a190',
    save_login: true,
    redact_at_rest: true
  })
};

fetch('https://api.pomerado.ai/v1/tools/{id}/changes', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.pomerado.ai/v1/tools/{id}/changes"

payload = {
    "change": "<string>",
    "example_input": {},
    "login_id": "login_0f8e2d1c4b3a49e8a7f6e5d4c3b2a190",
    "save_login": True,
    "redact_at_rest": True
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "id": "job_0f8e2d1c4b3a49e8a7f6e5d4c3b2a190",
  "type": "run",
  "status": "queued",
  "tool_id": "<string>",
  "input_request": {
    "id": "req_0f8e2d1c4b3a49e8a7f6e5d4c3b2a190",
    "expires_at": "<string>",
    "answer_url": "<string>",
    "message": "<string>",
    "questions": [
      {
        "id": "<string>",
        "prompt": "<string>",
        "type": "choice",
        "options": [
          {
            "id": "<string>",
            "label": "<string>"
          }
        ],
        "allow_other": true,
        "allow_note": true
      }
    ]
  },
  "result": "<unknown>",
  "result_status": "available",
  "result_expires_at": "<string>",
  "write_status": "not_attempted",
  "login_save": {
    "status": "saved",
    "login_id": "<string>",
    "reason": "<string>"
  },
  "error": {
    "error": {
      "code": "<string>",
      "message": "<string>",
      "retryable": true,
      "docs_url": "<string>",
      "details": {}
    }
  },
  "message": "<string>",
  "maintenance": {
    "status": "repairing",
    "result_recovered": true,
    "message": "<string>",
    "deadline_at": "<string>"
  },
  "build": {
    "integration_id": "int_0f8e2d1c4b3a49e8a7f6e5d4c3b2a190",
    "stage": "queued",
    "stages": [
      {
        "key": "queued",
        "label": "<string>",
        "status": "done",
        "started_at": "<string>",
        "completed_at": "<string>"
      }
    ],
    "eta": {
      "min_seconds": 123,
      "max_seconds": 123
    },
    "example_result": "<unknown>",
    "existing_tool_id": "<string>",
    "change": {
      "revision_id": "<string>",
      "previous_revision_id": "<string>",
      "write_started": true
    }
  },
  "watch_url": "<string>",
  "created_at": "<string>",
  "updated_at": "<string>",
  "completed_at": "<string>",
  "tip": "<string>"
}

{
  "id": "job_0f8e2d1c4b3a49e8a7f6e5d4c3b2a190",
  "type": "run",
  "status": "queued",
  "tool_id": "<string>",
  "input_request": {
    "id": "req_0f8e2d1c4b3a49e8a7f6e5d4c3b2a190",
    "expires_at": "<string>",
    "answer_url": "<string>",
    "message": "<string>",
    "questions": [
      {
        "id": "<string>",
        "prompt": "<string>",
        "type": "choice",
        "options": [
          {
            "id": "<string>",
            "label": "<string>"
          }
        ],
        "allow_other": true,
        "allow_note": true
      }
    ]
  },
  "result": "<unknown>",
  "result_status": "available",
  "result_expires_at": "<string>",
  "write_status": "not_attempted",
  "login_save": {
    "status": "saved",
    "login_id": "<string>",
    "reason": "<string>"
  },
  "error": {
    "error": {
      "code": "<string>",
      "message": "<string>",
      "retryable": true,
      "docs_url": "<string>",
      "details": {}
    }
  },
  "message": "<string>",
  "maintenance": {
    "status": "repairing",
    "result_recovered": true,
    "message": "<string>",
    "deadline_at": "<string>"
  },
  "build": {
    "integration_id": "int_0f8e2d1c4b3a49e8a7f6e5d4c3b2a190",
    "stage": "queued",
    "stages": [
      {
        "key": "queued",
        "label": "<string>",
        "status": "done",
        "started_at": "<string>",
        "completed_at": "<string>"
      }
    ],
    "eta": {
      "min_seconds": 123,
      "max_seconds": 123
    },
    "example_result": "<unknown>",
    "existing_tool_id": "<string>",
    "change": {
      "revision_id": "<string>",
      "previous_revision_id": "<string>",
      "write_started": true
    }
  },
  "watch_url": "<string>",
  "created_at": "<string>",
  "updated_at": "<string>",
  "completed_at": "<string>",
  "tip": "<string>"
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "docs_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "docs_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "docs_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "docs_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "docs_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "docs_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "docs_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "docs_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "docs_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "docs_url": "<string>",
    "details": {}
  }
}

Details

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 and may only add optional ones.
One change per tool at a time from your account. Another while yours is under way answers change_pending.
Callers: an API key, an MCP OAuth token or a Dashboard session.
Permission: tools:build.
Effect: Creates or changes something.
Errors: idempotency_conflict, quota_exceeded, quota_expired, acceptance_unknown, not_found, save_forbidden, account_selection_required, saved_login_conflict, login_identity_conflict, legacy_duplicate_saved_logins, saved_login_unsettled, not_configured, change_pending, and the errors any request can get.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

Idempotency-Key

string

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. 1 to 200 letters, digits, _ or -, such as a UUID

Pattern: ^[A-Za-z0-9_-]{1,200}$

Path Parameters

string

required

a tool ID: tool_ and 32 lowercase hex digits

Example:

"tool_0f8e2d1c4b3a49e8a7f6e5d4c3b2a190"

Body

application/json

change

string

required

What the tool should do differently, in plain words

Required string length: 1 - 2000

example_input

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

The saved login to sign in with, when the site has several

Example:

"login_0f8e2d1c4b3a49e8a7f6e5d4c3b2a190"

A login for this call, used only when the site has no saved login: a username (or email, phone or account number) and password, or mode "code" without a password when the site sends a code. It passes through your client and model provider; without it, the run asks the person on its answer page.

Show child attributes

Save login for later runs (requires login)

redact_at_rest

boolean

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.

Response

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

string

required

a job ID: job_ and 32 lowercase hex digits

Example:

"job_0f8e2d1c4b3a49e8a7f6e5d4c3b2a190"

type

enum<string>

required

Available options:

run,

build

status

enum<string>

required

Available options:

queued,

running,

needs_input,

succeeded,

failed,

cancelled

tool_id

string | null

required

input_request

object | null

required

Show child attributes

result

any

required

result_status

enum<string> | null

required

Available options:

available,

delivered,

expired

result_expires_at

string | null

required

a string to be decoded into a Date

write_status

enum<string> | null

required

Available options:

not_attempted,

may_have_applied,

applied,

not_applied

Show child attributes

error

object | null

required

Show child attributes

message

string | null

required

maintenance

object | null

required

Show child attributes

build

object | null

required

Show child attributes

watch_url

string

required

created_at

string

required

a string to be decoded into a Date

updated_at

string

required

a string to be decoded into a Date

completed_at

string | null

required

a string to be decoded into a Date

tip

string

Overview

Account

Runs

Builds

Jobs

Tools and integrations

Files

Webhooks

Saved logins

2FA

Login access

Team

API keys

Connected apps

Usage and quota

Billing

Request a change to a tool

Authorizations

Headers

Path Parameters

Body

Response