Resources

Discover

GET /v1/agents/resources/discover is public. Query with q, category, provider, status, min_score, cursor, and limit (1-100, default 50). Items include the canonical slug, description, run kind, pricing summary, structured pricing, and the next cursor.

curl -sS "https://api.deva.me/v1/agents/resources/discover?q=search&limit=5"

The response is { items, total, next_cursor, next }. Each item includes provider, slug, name, description, categories, pricing_summary, numeric unit_price_usd when available, payable_with, run_kind, provider IDs, popularity, structured pricing, pricing_model, and optional relevance_score.

Inspect

Inspect is public and returns the cached input_schema, pricing, defaults, caps, build metadata, and the suggested next URL. Never guess a resource's parameters.

curl -sS "https://api.deva.me/v1/agents/resources/inspect/$SLUG"

Estimate

Estimate is public, makes no upstream call, does not charge, and never fails for a missing cap. It returns amount_usd, amount_credits, deterministic, cap_usd, cap_credits, min_charge_usd, a breakdown, and a basis; only basis "exact" predicts the actual charge.

curl -sS -X POST "https://api.deva.me/v1/agents/resources/estimate/$SLUG" \
  -H "Content-Type: application/json" \
  -d '{"params": {}, "maxTotalChargeUsd": 0.25}'

Run

POST /v1/agents/resources/run/{slug} requires a key with RESOURCE:RUN (or *) and returns HTTP 202 with a run_id. A tool without a fixed positive price (pay-per-event, free, or an unresolvable per-result count) requires maxTotalChargeUsd at the top level of the request body — run ignores a cap nested inside params and returns CAP_REQUIRED. Idempotency-Key is optional; replaying the same value returns the existing run even if params differ. POST performs preflight checks but does not charge.

curl -sS -X POST "https://api.deva.me/v1/agents/resources/run/$SLUG" \
  -H "Authorization: Bearer $DEVA_API_KEY" \
  -H "Idempotency-Key: your-stable-run-id" \
  -H "Content-Type: application/json" \
  -d '{"params": {}, "maxTotalChargeUsd": 0.25}'

{
  "run_id": "run_...",
  "status": "running",
  "poll": "/v1/agents/resources/runs/run_...",
  "max_total_charge_credits": 0.25,
  "next": { "poll_url": "/v1/agents/resources/runs/run_..." }
}

Poll

GET /v1/agents/resources/runs/{run_id} requires RESOURCE:READ (or *). The first poll that observes a terminal upstream state settles the run idempotently; a reconciliation cron settles runs nobody polls. Failed and empty runs can still have credits_charged, and a cap-stopped run settles as succeeded with cap_hit true and partial items, so use the returned charge rather than inferring cost from the balance.

curl -sS "https://api.deva.me/v1/agents/resources/runs/$RUN_ID" \
  -H "Authorization: Bearer $DEVA_API_KEY"

Poll every 3-5 seconds until status is succeeded or failed. Terminal responses can include credits_charged, actual_cost_usd, max_total_charge_credits, cap_hit, items, dataset_id, result_count, usage_breakdown, message, and next.

Settlement

The first poll that observes a terminal state settles the run idempotently; a reconciliation cron settles runs nobody polls, so a run always settles eventually.

• Read credits_charged from the terminal response for the actual cost — don't infer it by diffing your balance.
• A run stopped by its cap settles as succeeded with cap_hit: true and the partial items collected up to that point.
• Failed or empty runs can still charge credits.

Robust run loop

1. POST run with a stable Idempotency-Key (and a top-level maxTotalChargeUsd if the tool needs one → Governing spend).
2. Poll every 3–5s to a terminal status.
3. On a transient error (UPSTREAM_*, 429), retry with the same key after Retry-After.
4. Record credits_charged; handle cap_hit.

For the pricing model see Pricing & settlement; for error shapes and rate limits see Errors & rate limits.