Start

Types and HTTP clients

Use the public REST API with generated TypeScript types, openapi-fetch, curl or standard-library Python. No AI Power Ups SDK is required.

Generated types (any language)

The public document has one operation per capability with operationId execute<Name> and a named request component <Name>Request, so any OpenAPI 3.1 generator produces a typed client. For TypeScript (--default-non-nullable=false keeps request fields that have a server-side default optional; without it openapi-typescript marks them required):

# In a new Node.js 20+ project, install this checked generator/compiler pair
npm install --save-dev --save-exact openapi-typescript@7.13.0 typescript@5.9.3 @types/node@20.19.0
npm install --save-exact openapi-fetch@0.17.0

# Generate types; preserve optional request fields with server-side defaults
npx openapi-typescript https://api.powerups-ai.store/v1/openapi.public.json -o ./ai-power-ups.d.ts --default-non-nullable=false

usage.mts

import createClient from "openapi-fetch";
import type { paths, components } from "./ai-power-ups.js";

type HotelsRequest = components["schemas"]["HotelsSearchRequest"];   // one named type per capability
type ExecuteResponse = components["schemas"]["ExecuteResponse"];

const client = createClient<paths>({
  baseUrl: "https://api.powerups-ai.store",
  headers: { Authorization: `Bearer ${process.env.AIPA_API_KEY}` },
});

const body: HotelsRequest = {
  destination: "Lisbon", check_in: "2026-10-09", check_out: "2026-10-11", adults: 2, currency: "EUR",
};
const { data, error, response } = await client.POST("/v1/capabilities/hotels.search/execute", { body });
if (error) throw new Error(`${response.status} ${error.error.code}: ${error.error.message}`);
const first = data.results[0];   // HotelsSearchRecord: record_id, title, url?, snippet?, price_per_night?, …

Check the example

npx tsc usage.mts --module NodeNext --target ES2022 --strict --noEmit

These generator and compiler versions are checked together. If your application uses another TypeScript version, generate the declaration file in a separate project with this pair, then check it with your application's compiler before adopting it.

Response envelopes are named too (ExecuteResponse, RecordFollowUpResponse, ErrorEnvelope, Balance…). Each concrete execute operation returns <Name>ExecuteResponse, whose records are <Name>Record: the base keys plus that capability's documented keys as optional properties, extra keys allowed. Follow-up responses use the generic ExecuteResponse.

TypeScript client from source

The thin TypeScript client and samples are available in source release v1.0.4. The client package version is 0.1.0; it is not published on npm. Use Node.js 20 or later to build and pack the tagged source:

Build the source package

git clone --branch v1.0.4 --depth 1 https://github.com/RoeySmallTree/ai-power-apps.git
cd ai-power-apps
npm ci --prefix sdk/typescript
npm pack ./sdk/typescript --pack-destination /tmp --json

The JSON output reports ai-power-ups-api-0.1.0.tgz. From your own application directory, install that local artifact:

Install in your application

npm install /tmp/ai-power-ups-api-0.1.0.tgz

TypeScript

import { AiPowerUps } from "@ai-power-ups/api";

const aipa = new AiPowerUps({ apiKey: process.env.AIPA_API_KEY! });
const page = await aipa.execute("academic.search", { query: "transformer attention", num: 3 });
for (const record of page.results) console.log(record.title);

The client README covers follow-ups, bounded pagination and retry behavior. Keep API keys on your server. The package checks compile a clean tarball consumer with library checking both enabled and disabled; importing source directly is not the installation path.

Python

The quickstart shows a standard-library client you can copy. The full Python sample in v1.0.4 runs free academic searches, follow-ups, cached details and invalid-input checks. Use Python 3.10 or later; no Python package installation is required.

From the tagged repository root

AIPA_API_KEY=your_server_side_key python3 samples/python/quickstart.py

Acceptance checks

Follow the acceptance checklist in the quickstart using a free capability and sequential requests. Run those checks against production with a key from a Free account to confirm your integration before adding paid capabilities.