Heista Intelligence API
Free, read-only access to Heista's decoded corpus (hooks, formulas, decoded ads).
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/heista-co:heista-co-intelligence-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Heista Intelligence API
version: 1.0.0
description: 'Creative intelligence as an API. Decode any video ad, extract brand intelligence from any URL or document, generate scripts in any brand''s voice, and browse the decoded corpus for free.
## Surfaces
- **Decode** — turn any video ad URL into a structural formula. Beats, hooks, psychology, visual playbook.
- **PowerSource** — 14-section brand intelligence from a URL, internal documents, or both.
- **Adscript** — generate 1–5 ad scripts from a proven structure + a PowerSource. Token-metered.
- **Files** — upload PDF/DOCX/TXT/MD for use in PowerSource docs mode.
- **Intelligence reads** — free corpus access (hook patterns, ad formulas, decoded ads).
- **Account** — credit balance, monthly usage, pricing.
## Pricing
- Decode: **$0.15** (≤60s) / **$0.20** (61–120s)
- PowerSource: **$1.00** (URL or docs only) / **$2.00** (URL + docs)
- Adscript: **token-metered**, typically **$0.02–$0.05** per script
- Intelligence reads, Files API: **free**
- Failed jobs auto-refund. Duplicate inputs (same org) return cached results at no charge.
## Authentication
Bearer header on every request:
```
Authorization: Bearer hst_live_your_key
```
Production keys are prefixed `hst_live_`; test keys are `hst_test_`. Get yours at heista.co/api-console.
## Errors
All errors follow RFC 9457 Problem Details. The same envelope shape across every endpoint; see the `ProblemDetails` schema.
Spending-cap and circuit-breaker errors include a `reason` field (`cap_hourly`, `cap_daily`, `cap_monthly`, `cap_key_daily`, `cap_key_monthly`, `circuit_open`). Insufficient-credits errors include `top_up_url`, `current_balance`, and `required` extensions.
## Rate limits
Per API key, per endpoint group. Every response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` (epoch ms). On 429 you also get `Retry-After` (seconds).'
contact:
name: Heista Support
email: support@heista.co
url: https://heista.co
termsOfService: https://heista.co/terms
license:
name: Proprietary
url: https://heista.co/terms
servers:
- url: https://www.heista.co/api/v1
description: Production
- url: http://localhost:3000/api/v1
description: Local development
security:
- bearerAuth: []
tags:
- name: Intelligence
description: Free, read-only access to Heista's decoded corpus (hooks, formulas, decoded ads).
paths:
/intelligence/hooks:
get:
tags:
- Intelligence
summary: Hook intelligence from the decoded corpus
description: Returns proven hook patterns matched to vertical / hook_type / marketing_angle. Free.
operationId: getHookIntelligence
parameters:
- name: vertical
in: query
schema:
type: string
- name: hook_type
in: query
schema:
type: string
- name: marketing_angle
in: query
schema:
type: string
responses:
'200':
description: Hook intelligence
content:
application/json:
schema:
type: object
properties:
filters:
type: object
count:
type: integer
results:
type: array
items:
$ref: '#/components/schemas/HookIntelligenceResult'
/intelligence/formulas:
get:
tags:
- Intelligence
summary: Ad formula blueprints
description: Clustered structural blueprints. Filter by vertical, creative_format, marketing_angle, algo_intent, hook_type. Free.
operationId: getAdFormulas
parameters:
- name: vertical
in: query
schema:
type: string
- name: creative_format
in: query
schema:
type: string
- name: marketing_angle
in: query
schema:
type: string
- name: algo_intent
in: query
schema:
type: string
- name: hook_type
in: query
schema:
type: string
- name: limit
in: query
schema:
type: integer
default: 5
minimum: 1
maximum: 10
responses:
'200':
description: Formula corpus results
content:
application/json:
schema:
type: object
properties:
filters:
type: object
count:
type: integer
formulas:
type: array
items:
$ref: '#/components/schemas/Formula'
/intelligence/decoder:
get:
tags:
- Intelligence
summary: Individual decoded ads from the corpus
description: Sorted by active_days descending, deduplicated by brand. Filter by vertical, creative_format, marketing_angle, hook_type, algo_intent, brand. Free.
operationId: getDecodedAds
parameters:
- name: vertical
in: query
schema:
type: string
- name: creative_format
in: query
schema:
type: string
- name: marketing_angle
in: query
schema:
type: string
- name: hook_type
in: query
schema:
type: string
- name: algo_intent
in: query
schema:
type: string
- name: brand
in: query
schema:
type: string
maxLength: 100
- name: limit
in: query
schema:
type: integer
default: 5
minimum: 1
maximum: 10
responses:
'200':
description: Decoded ads
content:
application/json:
schema:
type: object
properties:
filters:
type: object
count:
type: integer
ads:
type: array
items:
$ref: '#/components/schemas/DecodedAd'
webhooks:
powersource_complete:
post:
summary: PowerSource job completion notification
description: 'Sent to `webhook_url` (if provided on submission) when a PowerSource job reaches a terminal state (`completed` or `failed`).
The body is signed with HMAC-SHA256 using your org''s webhook secret. Verify the `X-Heista-Signature` header — format: `t=,v1=`. Compute `HMAC-SHA256(secret, "{t}.{raw_body}")` and compare.'
requestBody:
content:
application/json:
schema:
type: object
required:
- event
- job_id
- status
properties:
event:
type: string
enum:
- powersource.completed
- powersource.failed
job_id:
type: string
format: uuid
brief_id:
type: string
format: uuid
nullable: true
status:
type: string
enum:
- completed
- failed
price_cents:
type: integer
nullable: true
completed_at:
type: string
format: date-time
nullable: true
error:
type: string
nullable: true
responses:
2XX:
description: Webhook acknowledged. Heista retries non-2XX responses with exponential backoff (up to 5 attempts).
tags:
- Intelligence
components:
schemas:
Formula:
type: object
properties:
id:
type: string
name:
type: string
rationale:
type: string
nullable: true
identity:
type: object
additionalProperties: true
structure:
type: object
properties:
beat_count:
type: integer
total_duration:
type: number
beats:
type: array
items:
type: object
additionalProperties: true
visual_direction:
type: object
nullable: true
additionalProperties: true
confidence_level:
type: string
enum:
- HIGH
- MEDIUM
- LOW
confidence_score:
type: number
avg_active_days:
type: integer
nullable: true
source_ad_count:
type: integer
source_ads:
type: array
items:
type: object
properties:
id:
type: string
url:
type: string
format: uri
brand:
type: string
nullable: true
vertical:
type: string
product_type:
type: string
nullable: true
DecodedAd:
type: object
properties:
id:
type: string
decode_url:
type: string
format: uri
brand:
type: string
vertical:
type: string
marketing_angle:
type: string
active_days:
type: integer
nullable: true
duration_seconds:
type: number
nullable: true
classification:
type: object
properties:
creative_format:
type: string
video_type:
type: string
algo_intent:
type: string
behavioural_role:
type: string
psychological_mission:
type: string
offer_state:
type: string
beat_count:
type: integer
beats:
type: array
items:
type: object
additionalProperties: true
beat_sequence:
type: string
HookIntelligenceResult:
type: object
properties:
hook_type:
type: string
hook_type_name:
type: string
psychology:
type: string
short_def:
type: string
long_description:
type: string
corpus_count:
type: integer
intelligence:
type: object
additionalProperties: true
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: hst_live_xxx (production) or hst_test_xxx (test)
description: API key issued at heista.co/api-console.