Developers
API quickstart
Make your first API call in five minutes with curl, PHP or JavaScript, then register a webhook endpoint.
On this page
In five minutes you will create a test key, read your sandbox balance, and register a webhook endpoint. Test keys are free and never touch real credits.
1. Create a test key#
- Sign in and open Developers → API keys.
- Choose Create key, name it (for example "Laptop"), pick Test and keep the default scopes. Add
webhooks:managefor step 3. - Copy the key. It starts with
mx_test_and is shown only once. - Save it as an environment variable, not in your code:
export MUTEXAI_API_KEY="mx_test_..."
2. Read your balance#
Call GET /v1/balance. A new test wallet holds 1,000 credits.
# Your test key from Developers → API keys. Keep it out of your code and your Git history.
export MUTEXAI_API_KEY="mx_test_..."
curl https://studio-api.mutexai.net/v1/balance \
-H "Authorization: Bearer $MUTEXAI_API_KEY"
<?php
// PHP 8.1+ with the curl extension. Read the key from the environment, never from code.
$apiKey = getenv('MUTEXAI_API_KEY');
$curl = curl_init('https://studio-api.mutexai.net/v1/balance');
curl_setopt_array($curl, [
CURLOPT_HTTPHEADER => [
'Authorization: Bearer '.$apiKey,
'Accept: application/json',
],
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 15,
]);
$body = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_RESPONSE_CODE);
curl_close($curl);
$data = json_decode($body, true);
if ($status !== 200) {
// Errors are Problem Details: a stable "code" and a "request_id" to quote to support.
throw new RuntimeException("{$data['code']}: {$data['detail']} (request {$data['request_id']})");
}
echo "Available credits: {$data['available']}\n";
// Node.js 18+ (fetch is built in). Run with: MUTEXAI_API_KEY=mx_test_... node balance.mjs
const response = await fetch('https://studio-api.mutexai.net/v1/balance', {
headers: {
Authorization: `Bearer ${process.env.MUTEXAI_API_KEY}`,
Accept: 'application/json',
},
});
const data = await response.json();
if (!response.ok) {
// Errors are Problem Details: a stable "code" and a "request_id" to quote to support.
throw new Error(`${data.code}: ${data.detail} (request ${data.request_id})`);
}
console.log(`Available credits: ${data.available}`);
The response:
{
"object": "balance",
"available": 1000,
"livemode": false,
"as_of": "2026-11-17T09:30:12Z"
}
Got 401 invalid_api_key? Check the header is exactly Authorization: Bearer mx_test_… with one space, and that you copied the whole key.
3. Register a webhook endpoint#
Webhooks tell your server when something happens, so you do not have to keep asking. Your endpoint must be a public HTTPS URL on port 443.
curl https://studio-api.mutexai.net/v1/webhook-endpoints \
-H "Authorization: Bearer $MUTEXAI_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 5f1c2a8e-3d4b-4c6a-9e7f-2b1d0c9a8e7f" \
-d '{
"url": "https://example.com/webhooks/studio",
"events": ["*"],
"description": "My shop backend"
}'
<?php
$apiKey = getenv('MUTEXAI_API_KEY');
$curl = curl_init('https://studio-api.mutexai.net/v1/webhook-endpoints');
curl_setopt_array($curl, [
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer '.$apiKey,
'Content-Type: application/json',
'Accept: application/json',
// A new random value per endpoint you create. Reuse it only to retry this same request.
'Idempotency-Key: '.bin2hex(random_bytes(16)),
],
CURLOPT_POSTFIELDS => json_encode([
'url' => 'https://example.com/webhooks/studio',
'events' => ['*'],
'description' => 'My shop backend',
]),
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 15,
]);
$endpoint = json_decode(curl_exec($curl), true);
curl_close($curl);
// The secret is shown only in this response. Store it like a password.
echo "Endpoint {$endpoint['id']} created. Secret: {$endpoint['secret']}\n";
import { randomUUID } from 'node:crypto';
const response = await fetch('https://studio-api.mutexai.net/v1/webhook-endpoints', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.MUTEXAI_API_KEY}`,
'Content-Type': 'application/json',
Accept: 'application/json',
// A new random value per endpoint you create. Reuse it only to retry this same request.
'Idempotency-Key': randomUUID(),
},
body: JSON.stringify({
url: 'https://example.com/webhooks/studio',
events: ['*'],
description: 'My shop backend',
}),
});
const endpoint = await response.json();
// The secret is shown only in this response. Store it like a password.
console.log(`Endpoint ${endpoint.id} created. Secret: ${endpoint.secret}`);
{
"object": "webhook_endpoint",
"id": "we_01JD3XK5Z3Q8W3J9P2R7M4N6T1",
"url": "https://example.com/webhooks/studio",
"description": "My shop backend",
"events": ["*"],
"status": "active",
"livemode": false,
"secret": "whsec_l4o3TXxE6X4qlVAr2QdIqT90Rz+5YZTC16ddLKVE7Tc=",
"disabled_at": null,
"created_at": "2026-11-17T09:31:40Z"
}
The Idempotency-Key header makes the request safe to retry: if the network fails, send it again with the same key and you will not get two endpoints. See Idempotency.
4. Send yourself a test event#
Open Developers → Webhooks, choose your endpoint and press Send test event. Your server receives a signed webhook.test event. The delivery, its status code and timing appear in the endpoint's delivery log, with a Resend button.
Next, verify the signature on your server.
5. Go live#
- Create a live key (
mx_live_…) with only the scopes your app needs. - Add your servers' IP addresses to its allowlist.
- Register your production webhook endpoint with the live key. Test and live endpoints are separate.
- Make sure your account has credits. Live calls spend real credits.
Next steps#
- Authentication: scopes, rolling and revoking keys.
- Errors: what to do with each error.
- API reference: every endpoint and field.
Still stuck? Email [email protected] with what you tried and, for API problems, the request_id.