Quickstart

Make your first call in about five minutes: get a key, run a capability, read the envelope, then follow up by id. The example uses academic.search, a free source, so it costs 0 credits and works on the Free plan.
5 minutesNeeds an accountcurl · TypeScript · Python

Create an API key

Sign up or log in, then create a key under API keys in your dashboard. It looks like apa_live_… and can be copied again from the dashboard at any time. Send it as Authorization: Bearer on every call.

Terminal
export AIPA_API_KEY="apa_live_…"   # a server-side secret
API=https://api.powerups-ai.store

# Confirm the key and balance
curl -s $API/v1/account -H "Authorization: Bearer $AIPA_API_KEY"
Keys are secrets
Anyone holding a key can spend your credits. Keep it on your server or command line; browsers on other origins cannot call the API. If a key leaks, revoke it from the dashboard right away. See Keys and security.

Run a capability

Every capability is one POST request with a typed body. Here is academic.search:

curl -s -X POST https://api.powerups-ai.store/v1/capabilities/academic.search/execute \
  -H "Authorization: Bearer $AIPA_API_KEY" -H "Content-Type: application/json" \
  -d '{"query":"transformer attention","sort":"cited","num":3}'

Read the envelope

Every capability returns the same envelope. results hold the records, and each has a record_id you can act on later.

200 OK · application/json
{
  "search_id": "redacted",
  "capability": "academic.search",
  "results": [
    {
      "record_id": "redacted",
      "title": "Exploiting Generative AI to Scale up Intelligent Tutoring Systems",
      "url": "https://doi.org/10.4230/lipics.itp.2023.19",
      "snippet": "As a present to Mizar on its 50th anniversary, we develop an AI/TP system that automatically proves about 60% of the Mizar theorems in the hammer setting. We also automatically prove 75% of the Mizar theorems when the automated provers are helped by using only the premises used in the human-written…",
      "year": 2023,
      "venue": "DROPS (Schloss Dagstuhl – Leibniz Center for Informatics)",
      "authors": [
        "Jakubův, Jan",
        "… 4 more"
      ],
      "cited_by": 79058,
      "type": "article",
      "open_access": true,
      "oa_url": "https://drops.dagstuhl.de/storage/00lipics/lipics-vol268-itp2023/LIPIcs.ITP.2023.19/LIPIcs.ITP.2023.19.pdf",
      "doi": "https://doi.org/10.4230/lipics.itp.2023.19",
      "openalex_id": "W4385245566"
    },
    "… 4 more"
  ],
  "result_count": 5,
  "has_more": true,
  "next": {
    "url": "/v1/follow-up",
    "actions": [
      "more",
      "… 1 more"
    ],
    "example": {
      "search_id": "redacted",
      "action": "more"
    }
  },
  "record_actions": [
    "details"
  ],
  "charged_credits": 0
}

Recorded from the production API on 2026-09-26 for {"query":"transformer attention","sort":"cited","num":5}. Long arrays are abridged, ids are redacted and the account's balance is left out; a live response carries balance: { used, cap, period_end }.

  • search_id and every record_id are minted by the API and live for 24 hours after last use.
  • next.actions lists the search actions this capability accepts and next.example is a follow-up body that is valid right now (or null when nothing applies).
  • charged_credits and balance are on every metered response.

Follow up by id

Pass the search_id back to page through results or change the query, or a record_id to run a record action such as details.

Terminal
# Next page (the search_id from step 2)
curl -s -X POST $API/v1/follow-up -H "Authorization: Bearer $AIPA_API_KEY" \
  -H "Content-Type: application/json" -d '{"search_id":"srch_…","action":"more"}'

# Open a record (free for this source; a repeat is served from cache)
curl -s -X POST $API/v1/follow-up -H "Authorization: Bearer $AIPA_API_KEY" \
  -H "Content-Type: application/json" -d '{"record_id":"rec_…","action":"details"}'
One call at a time
The API admits one metered call per account at a time and answers a concurrent one with 429 rate_limited. Wait for a response before sending the next one. See Credits and limits.

The same in TypeScript, typed

Generate types from the public OpenAPI document once at build time; the document has one operation per capability, so the body of each path is typed:

sh
# 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 } from "./ai-power-ups.js";

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

const { data, error, response } = await client.POST("/v1/capabilities/academic.search/execute", {
  body: { query: "transformer attention", sort: "cited", num: 3 },
});
if (error) throw new Error(`${response.status} ${error.error.code}: ${error.error.message}`);

for (const record of data.results) console.log(record.title, record.url);

if (data.has_more) {
  const more = await client.POST("/v1/follow-up", {
    body: { search_id: data.search_id, action: "more" },
  });
  // more.data is the same envelope with the same search_id
}
Check the example
npx tsc usage.mts --module NodeNext --target ES2022 --strict --noEmit

The same in Python

Python 3 (standard library only)
import json, os, urllib.request

API = "https://api.powerups-ai.store"
KEY = os.environ["AIPA_API_KEY"]  # server-side secret

def call(method, path, body=None):
    data = None if body is None else json.dumps(body).encode()
    req = urllib.request.Request(API + path, data=data, method=method, headers={
        "Authorization": f"Bearer {KEY}", "Content-Type": "application/json"})
    try:
        with urllib.request.urlopen(req, timeout=60) as res:
            return res.status, json.load(res)
    except urllib.error.HTTPError as err:
        return err.code, json.load(err)

status, page = call("POST", "/v1/capabilities/academic.search/execute",
                    {"query": "transformer attention", "sort": "cited", "num": 3})
if status != 200:
    raise SystemExit(f"{status} {page['error']['code']}: {page['error']['message']}")
for record in page["results"]:
    print(record["title"], record.get("url"))
if page["has_more"]:
    status, page = call("POST", "/v1/follow-up", {"search_id": page["search_id"], "action": "more"})

What to expect

  • GET /v1/account returns 200 with credits.cap of at least 500 on the Free plan.
  • Execute returns 200, capability academic.search, result_count 3, charged_credits 0.
  • more returns 200 with the same search_id and new record ids.
  • A second details on the same record returns cached: true and charged_credits 0.
  • An unknown key in the body returns 400 with violations[0].path naming it.
  • A bad key returns 401 with an x-ratelimit-limit: 60 header.

Next