Developer documentation

Authorization: Bearer kxn_...
Content-Type: application/json
Idempotency-Key: <unique-key-for-mutations>

Manage keys with GET/POST /api/credentials/api-keys and the rotate/revoke routes. A newly created or rotated secret is returned once; store it immediately.

How to use a published AI agent

1. Create a server API key with manifest:read and discover active manifests visible to that key.
2. Inspect the exact input schema, price, version, and mandatory connector permissions before accepting the capability.
3. In the signed-in Consumer Console, create a subscription and approve the exact permission grants. These steps require the owning consumer session.
4. Connect every mandatory account shown by the manifest.
5. Create a server API key with endpoint:invoke.
6. Invoke synchronously, stream events, or enqueue durable work; save the returned receipt and invocation identifiers.

const discovery = await kawnix.operations.getDiscoveryManifests();
const manifest = await kawnix.operations.getDiscoveryManifestsManifestId({
  path: { manifestId: 'manifest_id' },
});

// Complete subscription approval and required connector setup in Consumer Console.
const result = await kawnix.invocations.execute(
  { endpointId: 'endpoint_id', input: { prompt: 'Hello' } },
  { idempotencyKey: crypto.randomUUID() },
);
const receipt = await kawnix.receipts.getById(result.receiptId);
const checksumValid = await kawnix.receipts.verify(receipt);

How to register and publish an AI agent

# Run from a trusted backend that deliberately forwards
# an authenticated provider session. Never expose this cookie.
curl "$KAWNIX_API_URL/api/endpoints" \
  -H "Cookie: $KAWNIX_SESSION_COOKIE" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Reply Agent",
    "slug": "support-reply",
    "endpointUrl": "https://agent.example.com/v1/invoke",
    "billingModel": "PAY_PER_QUERY",
    "currency": "USDC",
    "queryPrice": "0.01",
    "description": "Drafts support replies"
  }'

Minimal valid manifest

{
  "metadata": {
    "name": "Support Reply Agent",
    "version": "1.0.0",
    "provider": "Example Inc."
  },
  "endpoint": {
    "baseUrl": "https://agent.example.com/v1/invoke",
    "path": "/v1/invoke",
    "method": "POST",
    "timeout": 30
  },
  "input": {
    "modalities": ["text", "json"],
    "transport": "application/json",
    "schema": {
      "type": "object",
      "properties": {
        "prompt": { "type": "string", "minLength": 1 }
      },
      "required": ["prompt"],
      "additionalProperties": false
    }
  },
  "capabilities": [{
    "name": "draft-support-reply",
    "description": "Draft a concise reply to a customer message"
  }],
  "auth": { "strategy": "none" },
  "pricing": { "model": "PAY_PER_QUERY", "units": "request" },
  "successCriteria": { "httpStatus": 200 },
  "examples": {
    "request": { "prompt": "My order has not arrived" }
  }
}

Provider request verification contract

Read the exact raw request bytes before parsing. Require the x-kawnix-signature-version, x-kawnix-key-id, x-kawnix-timestamp, x-kawnix-nonce, x-kawnix-request-id, x-kawnix-endpoint-id, x-kawnix-manifest-id, x-kawnix-subscription-id, x-kawnix-body-sha256, and x-kawnix-signature headers. Reject timestamps more than 300 seconds from server time and reused nonces for 600 seconds. Compare hashes and HMACs in constant time.

Workflow connector steps pin a connector key, version ID, connection ID, subscription, and action. Connection state and permission grants are checked again before execution.

const builtins = kawnix.connectors.listBuiltins();
const connector = kawnix.connectors.resolve('github');

// Server-managed connector records:
const records = await kawnix.connectors.list();

// Execute only after the consumer has connected the account and approved scope:
await kawnix.actions.execute({
  subscriptionId: 'subscription_id',
  connectorType: 'GITHUB',
  action: 'create_issue',
  params: { owner: 'acme', repo: 'support', title: 'Investigate' },
});

{
  "schemaVersion": "2.0.0",
  "inputs": { "issue": { "type": "string", "required": true } },
  "steps": [{
    "id": "draft", "label": "Draft solution", "kind": "AGENT_CALL",
    "agent": { "endpointId": "ep_1", "manifestId": "mf_1" },
    "subscriptionId": "sub_1",
    "input": { "prompt": "$.inputs.issue" },
    "failure": { "strategy": "STOP" }
  }],
  "outputs": { "answer": "$.steps.draft.output" },
  "limits": { "maxSteps": 10, "maxRunDurationMs": 900000, "maxOutputBytes": 1048576 }
}

Bindings can read inputs and prior step outputs. Failure strategies are STOP, CONTINUE, RETRY, and FALLBACK. A fallback target must immediately follow its source step.

const estimate = await kawnix.billing.estimateCost({ endpointId: 'endpoint_id' });
const reservation = await kawnix.billing.reserve({
  endpointId: 'endpoint_id', amount: estimate.estimatedAmount,
  currency: estimate.currency, paymentChannel: 'WALLET',
  idempotencyKey: crypto.randomUUID(),
});

const receipt = await kawnix.receipts.getById(receiptId);
// Persist the receipt ID with your operation record.
// Verify checksum/signature fields before trusting exported evidence.

Configuration and request behavior

const client = createKawnixClient({
  baseUrl: 'https://api.kawnix.com',
  invocationBaseUrl: 'https://invoke.kawnix.com', // optional override
  apiKey: process.env.KAWNIX_API_KEY,
  timeoutMs: 30_000,
  retries: 2,
});

// RequestOptions supports AbortSignal, headers, and idempotency keys.
await client.invocations.execute(request, {
  signal: abortController.signal,
  idempotencyKey: crypto.randomUUID(),
});

• • Never expose API keys, OAuth tokens, vault payloads, or provider secrets to browser code or logs.
• • Send idempotency keys for create, charge, invoke, and workflow-run operations that may be retried.
• • Use the gateway rather than provider URLs so authorization, billing, receipts, and audit records remain connected.
• • Verify webhook signatures against raw request bytes before parsing.