Developer tutorial

Call published skills from code

Publish a skill, create an API key, then call the generated endpoint directly or through the official TypeScript SDK.

Publish a skillCreate an API keyCall by API slug or skill id

Parameter rules

Skill variables use {{name}} syntax. Send values under the parameters object using the same names.

Authentication

Pass your API key as a Bearer token. Keep it server-side and never expose it in browser code.

@hzhw/aivo

Install @hzhw/aivo when you want typed client helpers.

Use the REST API

Every published skill exposes a stable endpoint that accepts parameters and an optional model id.

curl -X POST 'https://your-aivo-app.com/api/skills/blog-title-generator/execute' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -d '{
    "parameters": {
      "topic": "TypeScript SDKs",
      "audience": "startup founders"
    },
    "model": "<MODEL_ID>"
  }'

Use the TypeScript SDK

The SDK validates required skill parameters locally and keeps request handling consistent across apps.

import { AivoClient } from '@hzhw/aivo';

const client = new AivoClient({
  apiKey: process.env.AIVO_API_KEY!,
  baseUrl: 'https://your-aivo-app.com',
});

const response = await client.executeSkill('blog-title-generator', {
  topic: 'TypeScript SDKs',
  audience: 'startup founders',
});

console.log(response.result);

Response shape

Both API and SDK calls return generated content plus model, latency, usage, and credit metadata.

{
  "success": true,
  "data": {
    "result": "<AI generated content>",
    "model": "<MODEL_ID>",
    "durationMs": 1234,
    "usage": {
      "promptTokens": 50,
      "completionTokens": 200,
      "totalTokens": 250
    },
    "creditsConsumed": 1
  }
}