Aidelly Docs
REST API

SDK Generation

Generate type-safe client libraries from the OpenAPI spec using popular tools.

There are no official Aidelly SDKs, but you can generate type-safe client libraries in TypeScript, Python, and other languages directly from our OpenAPI spec. This guide covers popular tools and examples.

Download the OpenAPI Spec

Fetch the live spec:

curl -o openapi.yaml https://app.aidelly.ai/api/public/v1/openapi

Or reference it directly in generation tools:

https://app.aidelly.ai/api/public/v1/openapi

TypeScript with openapi-typescript

Generate a TypeScript type-safe client with zero dependencies:

Install

npm install openapi-typescript
npx openapi-typescript https://app.aidelly.ai/api/public/v1/openapi -o ./types.ts

Generate

npx openapi-typescript https://app.aidelly.ai/api/public/v1/openapi -o ./types.ts

This creates types.ts with full types for all endpoints:

// types.ts (auto-generated)
export type paths = {
  '/posts': {
    get: {
      parameters: {
        query: {
          page?: number;
          limit?: number;
          platform?: 'linkedin' | 'twitter' | 'facebook';
        };
        header: {
          'x-aidelly-workspace-id': string;
          'x-aidelly-brand-id'?: string;
        };
      };
      responses: {
        200: {
          content: {
            'application/json': {
              data: {
                items: Array<{
                  id: string;
                  platform: string;
                  content_text: string;
                  scheduled_at: string;
                }>;
              };
            };
          };
        };
      };
    };
    post: {
      // ... create post
    };
  };
  // ... other endpoints
};

Use Types

Create a typed client wrapper:

import type { paths } from './types';

type ListPostsResponse = paths['/posts']['get']['responses'][200];

async function listPosts(
  apiKey: string,
  workspaceId: string
): Promise<ListPostsResponse> {
  const response = await fetch(
    'https://app.aidelly.ai/api/public/v1/posts?page=1&limit=10',
    {
      headers: {
        Authorization: `Bearer ${apiKey}`,
        'x-aidelly-workspace-id': workspaceId,
      },
    }
  );

  if (!response.ok) {
    throw new Error(`Failed: ${response.status}`);
  }

  return response.json();
}

// Usage — fully typed
const posts = await listPosts('aidelly_live_xxx', 'ws_abc123');
const firstPost = posts.data.items[0]; // type: unknown (can be narrowed)

TypeScript with OpenAPI Generator

For a more featureful client with auto-generated request/response handling:

Install

npm install @openapitools/openapi-generator-cli

Generate

openapi-generator-cli generate \
  -i https://app.aidelly.ai/api/public/v1/openapi \
  -g typescript-axios \
  -o ./generated/aidelly-client

This generates a complete client library with:

  • Fully typed endpoints
  • Automatic request/response serialization
  • Built-in error handling
  • Request retry logic (optional)

Use Generated Client

import { Configuration, PostsApi } from './generated/aidelly-client';

const config = new Configuration({
  apiKey: 'aidelly_live_xxx',
  basePath: 'https://app.aidelly.ai/api/public/v1',
  baseOptions: {
    headers: {
      'x-aidelly-workspace-id': 'ws_abc123',
    },
  },
});

const postsApi = new PostsApi(config);

// Fully typed!
const response = await postsApi.listPosts({
  page: 1,
  limit: 10,
});

console.log(response.data.items);

Python with openapi-python-client

Generate a Python client:

Install

pip install openapi-python-client

Generate

openapi-python-client generate \
  --url https://app.aidelly.ai/api/public/v1/openapi \
  --output-dir ./aidelly_client

Use Generated Client

from aidelly_client import Client
from aidelly_client.api.posts import list_posts
from aidelly_client.models import ListPostsRequest

client = Client(
    base_url="https://app.aidelly.ai/api/public/v1",
    headers={
        "Authorization": "Bearer aidelly_live_xxx",
        "x-aidelly-workspace-id": "ws_abc123",
    }
)

posts = list_posts(
    client=client,
    page=1,
    limit=10
)

for post in posts.data.items:
    print(post.content_text)

Python with datamodel-code-generator

For Pydantic-based models with validation:

Install

pip install datamodel-code-generator

Generate

datamodel-codegen \
  --url https://app.aidelly.ai/api/public/v1/openapi \
  --output models.py \
  --target-python-version 3.10

Use Models

import httpx
from models import ListPostsResponse

async def fetch_posts(api_key: str, workspace_id: str):
    async with httpx.AsyncClient() as client:
        response = await client.get(
            "https://app.aidelly.ai/api/public/v1/posts",
            headers={
                "Authorization": f"Bearer {api_key}",
                "x-aidelly-workspace-id": workspace_id,
            },
            params={"page": 1, "limit": 10}
        )

        # Automatic validation
        data = ListPostsResponse.model_validate(response.json())
        return data.data.items

Go with go-swagger

Generate a Go client:

Install

go install github.com/go-swagger/go-swagger/cmd/swagger@latest

Generate

swagger generate client \
  -f https://app.aidelly.ai/api/public/v1/openapi \
  -t ./generated \
  -A aidelly-client

Use Generated Client

package main

import (
    "context"
    "fmt"

    httptransport "github.com/go-openapi/runtime/client"
    "github.com/go-openapi/strfmt"

    apiclient "your-module/generated/client"
    "your-module/generated/client/posts"
)

func main() {
    transport := httptransport.New("app.aidelly.ai/api/public/v1", "", []string{"https"})
    transport.DefaultAuthentication = httptransport.BearerToken("aidelly_live_xxx")

    client := apiclient.New(transport, strfmt.Default)

    params := posts.NewListPostsParams().
        WithXAidellyWorkspaceID("ws_abc123").
        WithPage(1).
        WithLimit(10)

    resp, err := client.Posts.ListPosts(context.Background(), params)
    if err != nil {
        panic(err)
    }

    fmt.Printf("Posts: %v\n", resp.Payload.Data.Items)
}

Java with OpenAPI Generator

Install

brew install openapi-generator

Generate

openapi-generator generate \
  -i https://app.aidelly.ai/api/public/v1/openapi \
  -g java \
  -o ./aidelly-java-client

Manual API Calls

If you prefer not to generate a client, make direct HTTP requests:

TypeScript (Fetch API)

async function createPost(
  content: string,
  platform: string
): Promise<{ id: string }> {
  const response = await fetch('https://app.aidelly.ai/api/public/v1/posts', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${process.env.AIDELLY_API_KEY}`,
      'x-aidelly-workspace-id': process.env.WORKSPACE_ID!,
      'Idempotency-Key': `post-${Date.now()}`,
    },
    body: JSON.stringify({
      content_text: content,
      platform: platform,
    }),
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`API Error: ${error.error.code}`);
  }

  const result = await response.json();
  return result.data;
}

Python (Requests)

import requests
import os

def create_post(content: str, platform: str) -> dict:
    response = requests.post(
        "https://app.aidelly.ai/api/public/v1/posts",
        headers={
            "Authorization": f"Bearer {os.environ['AIDELLY_API_KEY']}",
            "x-aidelly-workspace-id": os.environ["WORKSPACE_ID"],
            "Idempotency-Key": f"post-{int(time.time())}",
        },
        json={
            "content_text": content,
            "platform": platform,
        },
    )

    if response.status_code != 200:
        raise Exception(f"API Error: {response.json()['error']['code']}")

    return response.json()["data"]

Best Practices

Always:

  • Use the OpenAPI spec as the source of truth
  • Regenerate clients when the spec changes
  • Test generated clients with the actual API
  • Use version control for generated code or document the generation process
  • Handle rate limiting (check X-RateLimit-* headers)

Don't:

  • Manually modify generated code (regenerate instead)
  • Assume API behavior from code — consult the OpenAPI spec
  • Skip API documentation because you have generated types
  • Commit generated code without a reproduction recipe (use CI to generate on build)

See Also

Analytics Endpoints

Summary, unified, and insights endpoints — when to use each one.

Preview Features

Early-access API surface for features under active development — subject to change without notice.