Completions

Completions endpoints send messages to deployed Pickaxes and Agents.

Endpoints

POST /completions

Send a message to an API deployment programmatically. Use the deployment ID as the Bearer token in the Authorization header.

• Full URL: https://api.pickaxe.co/v1/completions

Request Fields

• message (string, optional): Use this for chat-style API deployments. This is the message sent to the deployed Pickaxe or Agent.
• inputs (object, optional): Use this for form-style API deployments. Provide key-value pairs that match the deployment's input fields. These keys are deployment-specific. For the real field IDs, check the deployment's API preview. Example: { "your_input_field_id": "value" }
• userId (string, optional): The identifier used to track the user making the request. If omitted, IP address tracking is used instead, which may be less reliable because multiple people can share the same IP address.
• conversationId (string, optional): A custom identifier used to preserve conversation context across requests. If omitted, a random conversation ID is generated automatically.
• pickaxeConfig (object, optional): Optional PickaxeConfig object to pass customer, account, routing, or other business context to Actions and MCP servers. Use the same shape as window.PickaxeConfig for script embeds: put global metadata in pickaxeConfig.metadata, or scope metadata to one deployment by nesting it under that deployment ID. The runtime receives the forwarded metadata as the JSON string environment variable PICKAXE_FRONTEND_PICKAXE_CONFIG. Client-only keys such as class, style, sso, watchdog, and parentPage are not forwarded. Example: { "metadata": { "customerId": "cus_123", "accountTier": "enterprise" }, "deployment-DEPLOYMENT_ID": { "metadata": { "region": "us-east-1" } } }
• imageUrls (string[], optional): Optional image URLs to include in the request for supported multimodal models. Each URL must begin with "https://" and end with a supported image extension such as .png, .webp, .gif, .jpg, or .jpeg.
• stream (boolean, optional): If true, the response is streamed back in real time using Server-Sent Events (SSE). Otherwise, the API returns a single JSON response. Defaults to false.

Examples

curl -X POST https://api.pickaxe.co/v1/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_DEPLOYMENT_API_KEY" \
-d '{
  "message": "Hello, how can I help you?"
}'