Cloud API

The Cloud Model API takes a current observation and returns a sequence of robot actions. The production Base URL is https://api.pokebot.com/v1. Configure PLATFORM_BASE_URL and PLATFORM_API_KEY as described in Account and API key.

Authenticate every request with Authorization: Bearer <API_KEY>. All paths below are relative to the Base URL. Keep credentials in your server or local control program.

EndpointsCopy Anchor Link

Start with the quickstart for your first call. See Tasks and sessions for turn and receipt handling in continuous tasks.

List modelsCopy Anchor Link

GET /models

Returns models available to your API key. Read an id from the response's data array and use it as the model in subsequent requests.

curl --fail-with-body "$PLATFORM_BASE_URL/models" \
  -H "Authorization: Bearer $PLATFORM_API_KEY"

A model ID is an API identifier. Use the returned value directly rather than deriving it from a product name.

Read model constraintsCopy Anchor Link

GET /models/{model_id}/schema

After selecting a model, use its ID to retrieve the schema. PLATFORM_MODEL below is the value selected from the model list.

curl --fail-with-body "$PLATFORM_BASE_URL/models/$PLATFORM_MODEL/schema" \
  -H "Authorization: Bearer $PLATFORM_API_KEY"

Read the schema again when switching models and prepare observations and actions according to the selected model's constraints.

Generate actionsCopy Anchor Link

POST /chat/completions

Send a JSON body containing a model ID and one user message with the current observation.

The text part contains instruction and state, encoded as a string with JSON.stringify(). Supply the image as a base64 data URL.

const request = {
  model: process.env.PLATFORM_MODEL,
  messages: [{
    role: "user",
    content: [
      {
        type: "text",
        text: JSON.stringify({ instruction, state })
      },
      {
        type: "image_url",
        image_url: { url: imageDataUrl }
      }
    ]
  }]
};

instruction describes the task, state contains the captured robot state, and imageDataUrl holds the corresponding camera image. See Observations and actions for the format, or Python and JavaScript and curl for complete examples.

Read actionsCopy Anchor Link

Actions are returned through an execute_actions tool call. Find it in choices[0].message.tool_calls, JSON-decode function.arguments, and read output.

const call = result.choices?.[0]?.message?.tool_calls?.find(
  (item) => item.function?.name === "execute_actions"
);
if (!call) throw new Error("Missing execute_actions result");
const { output } = JSON.parse(call.function.arguments);

output is an action sequence with 8 numbers per row. Read the row count from the returned array. See Observations and actions for field order and coordinates.

In a session response, metadata.action_shape is a JSON string describing the delivered actions. Parse it to check the array shape. inference_usage.output_shape describes the raw model output and may differ. After validating the delivered shape, the control program executes the actions and captures the next observation. The RoboAPI local runtime manages this loop and its execution receipts; custom integrations should follow Tasks and sessions.

Query requests and usageCopy Anchor Link

GET /requests/{request_id}

Use the inference response's X-Request-ID header to query the request. You can also obtain request_id from a session-turn query. The completion body's id (such as chatcmpl-…) is a different identifier and cannot be used here.

The Python example reads it through response._request_id; JavaScript uses response.headers.get("x-request-id"). Set REQUEST_ID to the actual value:

REQUEST_ID="<X_REQUEST_ID>"
curl --fail-with-body "$PLATFORM_BASE_URL/requests/$REQUEST_ID" \
  -H "Authorization: Bearer $PLATFORM_API_KEY"

The result includes status, code, started_at, finished_at, timings, and inference_usage. succeeded means inference completed; the control program's receipt confirms whether actions were executed. If a session request is interrupted before you receive its ID, query the saved response by session ID and turn before deciding what to execute.

usage may be null. Inference usage describes the computation for a call; refer to the Developer Console for account balance and billing.

Handle errorsCopy Anchor Link

Check the HTTP status before parsing a result. See Cloud API errors for authentication, access, input, and service errors.

Follow the Cloud quickstart for your first request. Once you have connected your own robot, the local HTTP API controls its local runtime.