DEVELOPERS

RelayMe Agent API: workflow quickstart

Discover workflows, inspect their input schema, estimate cost and submit asynchronous runs over HTTP. Retrieve results with a run ID to connect image and video workflows to your application.

Reviewed

Start with the API contract

Discovery endpoints below are public. Workflow and generation requests require account access and Bearer authentication.

The run lifecycle

  1. Discover a workflow and inspect its input schema
  2. Provide inputs and review the cost estimate
  3. Submit a run with a stable idempotency key
  4. Poll at the supplied interval for a terminal status and outputs

1. Find an available workflow

Create an API key in the developer area after signing in and keep it on your server. Replace the key, workflow ID and input node IDs in these examples with your own values.

export RELAYME_BASE_URL="https://api.relayme.ai"
export RELAYME_API_KEY="<your-api-key>"

curl "$RELAYME_BASE_URL/api/ai-tools/v1/workflows" \
  -H "Authorization: Bearer $RELAYME_API_KEY"

2. Inspect inputs and outputs

# Replace 123 with a workflow ID returned for your account.
export WORKFLOW_ID="123"
curl "$RELAYME_BASE_URL/api/ai-tools/v1/workflows/$WORKFLOW_ID/schema" \
  -H "Authorization: Bearer $RELAYME_API_KEY"

Supply inputs according to inputSchema. Check unsupportedNodes first: browser-only tool nodes may not execute on the server. Output keys correspond to outputSchema.

3. Estimate the run cost

# Replace text-1 with an input node ID from your workflow schema.
curl -X POST "$RELAYME_BASE_URL/api/ai-tools/v1/workflows/$WORKFLOW_ID/estimate" \
  -H "Authorization: Bearer $RELAYME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"inputs":{"text-1":"A clean product photo on a white background"}}'

Review estimatedCost, currency, per-node estimates and assumptions. exact: false means the estimate has uncertainty. Submit a run once its parameters and expected cost are acceptable.

4. Submit and save the run ID

# Create a unique key for each intended run; reuse it for retries of that run.
export RUN_KEY="product:YOUR-PRODUCT-ID:hero-image:v1"
curl -i -X POST "$RELAYME_BASE_URL/api/ai-tools/v1/workflows/$WORKFLOW_ID/runs" \
  -H "Authorization: Bearer $RELAYME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $RUN_KEY" \
  -d '{"inputs":{"text-1":"A clean product photo on a white background"}}'

A newly accepted run returns HTTP 202, Location, Retry-After and data.runId. An idempotent replay may return HTTP 200; read data.runId from that response too. Bind the idempotency key to one business operation: reuse it for network retries and use a new key for a new operation.

5. Poll for the result

export RUN_ID="<runId-from-the-202-response>"
curl "$RELAYME_BASE_URL/api/ai-tools/v1/workflow-runs/$RUN_ID" \
  -H "Authorization: Bearer $RELAYME_API_KEY"

Wait according to Retry-After or retryAfterSeconds. QUEUED, RUNNING and CANCEL_REQUESTED are not terminal. Read outputs on COMPLETED, inspect node errors on FAILED and stop polling on CANCELLED. Signed webhooks are also available when creating a run.

Frequently asked questions

What does the API support?

Workflow discovery, schemas, estimates, execution and cancellation, plus chat and direct image/video generation. Use the public OpenAPI and individual skills for the current contracts.

Does retrying create another workflow run?

Reuse the original Idempotency-Key for the same workflow-run request to avoid creating a duplicate run. Direct image/video generation does not offer the same idempotency guarantee; check task history after a timeout instead of blindly resubmitting.

Is an estimate the final charge?

No. Nodes that depend on generated upstream content may use placeholders and return exact: false with assumptions. Final cost depends on actual model usage and submitted calls.

Can a cancelled run still incur charges?

Yes. Cancellation stops scheduling subsequent nodes, but tasks already submitted to providers may complete and incur charges. Check inFlightTaskMayComplete and the terminal run status.

Build your integration

Validate a small workflow in the workspace, then connect it to your product through the API.

Create an account Credits and plans Video API selection guide