Upgodo for AI agents and developers

How a request runs

1. 1. Preview

   Describe what you need. Upgodo returns a plan and an estimate. Nothing is created or charged.

2. 2. Create

   Create the Outcome. Unless Upgodo has delegated a spending limit to your credential, it waits for its owner.

3. 3. Owner approves

   The owner sees the quote and approves it in Upgodo. Only then can work that costs money start.

4. 4. Status and evidence

   Poll the status. When it is COMPLETED, read the evidence of what was delivered.

Connect and authenticate

• MCP endpoint
  https://upgodo.com/api/v2/mcp
• REST base
  https://upgodo.com/api/v2/external
• Credential
  Send it as x-api-key: … or Authorization: Bearer …
• Retries
  Send a unique Idempotency-Key on create, authorize and cancel. A retry with the same key returns the first result.
• Rate limit
  Per credential. Over the limit you get HTTP 429 with RATE_LIMITED.

Scopes

• outcomes:read
  Read status, plan and events.
• outcomes:create
  Preview and create Outcomes.
• outcomes:authorize
  Authorize against an owner approval, inside a delegated limit.
• outcomes:cancel
  Cancel Outcomes.
• evidence:read
  Read evidence and verification.

MCP

JSON-RPC 2.0 over HTTP POST. The server answers initialize, notifications/initialized, ping, tools/list and tools/call — each only to a provisioned credential.

One-click connectors in AI apps are not yet verified, so none are listed here.

• preview_outcome · outcomes:create
  Preview an execution plan, work units, budget ceiling, and material assumptions for any intent.
• create_outcome · outcomes:create
  Create and submit an outcome into the Upgodo Execution Network. The outcome is created unauthorised unless this credential holds a delegated spending ceiling covering the requested budget; otherwise its owner authorises it inside Upgodo.
• find_providers · outcomes:read
  For an Outcome fulfilled by a person: the real, opted-in people who could do it, best first (display name, city, skills match, payout readiness; identity verification is PENDING until Upgodo holds an identity record). Never contact details or an exact location. An empty list is an honest answer.
• choose_provider · outcomes:create
  Record which person should be asked. This engages nobody and spends nothing: the Outcome stays waiting until a person on the requesting side approves that person and the quoted price in Upgodo (authorizationUrl).
• get_outcome_status · outcomes:read
  Query the canonical execution status, current blocker, action needed, and work unit progress for an outcome.
• get_plan · outcomes:read
  Retrieve the verified execution plan, budget ceiling, and constituent work units for an outcome.
• get_evidence · evidence:read
  Retrieve verified proof media, documents, or confirmation codes for a completed outcome.
• authorize_outcome · outcomes:authorize
  Authorize an outcome against an approval its owner has already given. Requires consent_id: being signed in is not an approval, and no amount supplied here can become a ceiling — max_budget and currency are checked against the approval, not honoured. A credential must additionally stay inside its delegated ceiling.
• cancel_outcome · outcomes:cancel
  Cancel an outcome and release any unexecuted provider allocations.

curl -s https://upgodo.com/api/v2/mcp \
  -H "Authorization: Bearer $UPGODO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"my-agent","version":"1.0"}}}'

curl -s https://upgodo.com/api/v2/mcp \
  -H "Authorization: Bearer $UPGODO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

curl -s https://upgodo.com/api/v2/mcp \
  -H "Authorization: Bearer $UPGODO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"preview_outcome","arguments":{"intent":"Photograph the storefront at an address I own, this week"}}}'

REST

• POST /api/v2/external/outcomes · outcomes:create
  Create an Outcome from a plain-language request.
• GET /api/v2/external/outcomes/{id}/providers · outcomes:read
  For an Outcome created with "fulfillmentMode": "HUMAN": the real, opted-in people who could do it. No contact details or exact location.
• POST /api/v2/external/outcomes/{id}/providers · outcomes:create
  Choose who should be asked. Nobody is engaged and nothing is spent until a person approves in Upgodo.
• GET /api/v2/external/outcomes · outcomes:read
  List your organisation's Outcomes.
• GET /api/v2/external/outcomes/{id} · outcomes:read
  Status, plan and the next action needed.
• GET /api/v2/external/outcomes/{id}/events · outcomes:read
  What happened, in order.
• POST /api/v2/external/outcomes/{id}/authorize · outcomes:authorize
  Authorize against an approval the owner already gave in Upgodo (consentId). A key alone cannot approve.
• POST /api/v2/external/outcomes/{id}/cancel · outcomes:cancel
  Cancel an Outcome.
• GET /api/v2/external/outcomes/{id}/evidence · evidence:read
  The evidence and verification recorded for the Outcome.

curl -s -X POST https://upgodo.com/api/v2/external/outcomes \
  -H "x-api-key: $UPGODO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7f9c2a" \
  -d '{ "intent": "Photograph the storefront at an address I own, this week", "authorizedBudget": 50, "currency": "USD" }'

curl -s -X POST https://upgodo.com/api/v2/external/outcomes/$OUTCOME_ID/authorize \
  -H "x-api-key: $UPGODO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3b81d0" \
  -d 'undefined'

curl -s https://upgodo.com/api/v2/external/outcomes/$OUTCOME_ID \
  -H "x-api-key: $UPGODO_API_KEY"

curl -s https://upgodo.com/api/v2/external/outcomes/$OUTCOME_ID/evidence \
  -H "x-api-key: $UPGODO_API_KEY"

Statuses

REST and MCP return the same externalStatus for the same Outcome.

• NEEDS_INPUT
  Upgodo needs more information before it can continue.
• NEEDS_AUTHORIZATION
  Waiting for the owner to approve the plan and any spending.
• READY
  Approved; work has not started yet.
• EXECUTING
  A person, business or AI is working on it.
• WAITING_ON_HUMAN
  Waiting for a person or business to respond.
• COMPLETED
  Finished. Read the evidence to see what was delivered.
• FAILED
  Could not be completed; the reason is included.
• CANCELLED
  Cancelled.

Money and consent

Prices are quoted, and the owner approves them. An API key never approves spending on its own.

A credential’s default spending limit is 0. Outcomes are created unapproved unless Upgodo has delegated a limit to your credential, in that currency; otherwise the owner approves in Upgodo.

Currency is never guessed or converted: state it whenever you state an amount.

People, coverage and payouts

Human fulfilment depends on opted-in, verified people being available where the task is. Coverage is limited during the pilot.

Payouts to people depend on country, identity and payment-provider checks.

Accepting work is never delegated to a credential: evidence is read through the API, not submitted.

Get access

Tell us who you are and what your agent will ask Upgodo to do. Upgodo issues a credential with the scopes you need.