Build a tool
curl --request POST \
--url https://api.pomerado.ai/v1/builds \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"task": "<string>",
"site_url": "<string>",
"start_url": "<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({
task: '<string>',
site_url: '<string>',
start_url: '<string>',
example_input: {},
login_id: 'login_0f8e2d1c4b3a49e8a7f6e5d4c3b2a190',
save_login: true,
redact_at_rest: true
})
};
fetch('https://api.pomerado.ai/v1/builds', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.pomerado.ai/v1/builds"
payload = {
"task": "<string>",
"site_url": "<string>",
"start_url": "<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_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>"
},
"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>"
},
"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_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>"
},
"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>"
},
"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": {}
}
}Builds
Build a tool
Build a new tool for a task on a website. A build takes about 10 minutes and runs the requested example once; the tool is reused after that. Answers its job at once; follow it with GET /v1/jobs/ or job webhooks. A build that finds an existing tool covering the task hands it over as tool_id and build.existing_tool_id. Builds for ticket, bank and government sites are refused with site_not_supported.
POST
/
v1
/
builds
Build a tool
curl --request POST \
--url https://api.pomerado.ai/v1/builds \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"task": "<string>",
"site_url": "<string>",
"start_url": "<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({
task: '<string>',
site_url: '<string>',
start_url: '<string>',
example_input: {},
login_id: 'login_0f8e2d1c4b3a49e8a7f6e5d4c3b2a190',
save_login: true,
redact_at_rest: true
})
};
fetch('https://api.pomerado.ai/v1/builds', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.pomerado.ai/v1/builds"
payload = {
"task": "<string>",
"site_url": "<string>",
"start_url": "<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_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>"
},
"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>"
},
"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_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>"
},
"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>"
},
"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": {}
}
}Authentication:
Authorization: Bearer <token> with Dashboard session, Pomerado MCP OAuth token, API key, integration API key.
Permission: tools:build.
Effect: Write: creates or changes something in your account.
Errors: effect_required (400), invalid_request (400), unauthorized (401), reauthentication_required (401), save_forbidden (403), site_not_supported (403), forbidden (403), not_found (404), idempotency_conflict (409), quota_expired (409), account_selection_required (409), saved_login_conflict (409), login_identity_conflict (409), legacy_duplicate_saved_logins (409), saved_login_unsettled (409), request_too_large (413), quota_exceeded (429), internal_error (500), not_configured (501), acceptance_unknown (503), temporarily_unavailable (503). Every error has the same envelope.Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Headers
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}$Body
application/json
What the tool should do, in words
Required string length:
1 - 20000The website's https address; omit it for offline parsing, which is a read
Maximum string length:
2048The exact https page on site_url the build starts on, path, query and fragment kept
Maximum string length:
4096read when the tool only looks things up; write when it changes the website (submitting, booking, saving a form, uploads, account updates); ask to have the build ask first. A website build needs one.
Available options:
read, write, ask The input of the one real example the build runs
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) with its password, or mode "code" and no password when the site sends a code. It reaches this caller's client and model provider; without one, the run asks the person on its answer page.
Show child attributes
Show child attributes
Keep login as a saved login (requires login)
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
a job ID: job_ and 32 lowercase hex digits
Example:
"job_0f8e2d1c4b3a49e8a7f6e5d4c3b2a190"
Available options:
run, build Available options:
queued, running, needs_input, succeeded, failed, cancelled Show child attributes
Show child attributes
a string to be decoded into a Date
Available options:
not_attempted, may_have_applied, applied, not_applied Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
a string to be decoded into a Date
a string to be decoded into a Date
a string to be decoded into a Date