AIC Developer Portal

Authentication & IP Whitelisting

All dev_* commands require your request to originate from an IP-whitelisted machine. The whitelist is the primary auth gate — no additional password is needed for API calls.

How to get whitelisted

Find your public IP at whatismyip.com
Email support@annoying-is-caring.com with your IP and reason for access
Once approved, your IP will be added and the status bar above will show WHITELISTED

Note: If your IP changes (VPN, travel, ISP rotation), you will need to request whitelisting again.

API endpoint (POST JSON body or GET query string):

https://stgyjm2ca1.execute-api.us-east-1.amazonaws.com/lol_joke_status

CLI Tool

Download and install the command-line interface:

# 1. Download
curl -o aic-cli.zip https://d2f64d7f2dnmit.cloudfront.net/mobile/aic-cli.zip

# 2. Unzip
mkdir -p aic-cli && cd aic-cli && unzip ../aic-cli.zip

# 3. Install dependencies
pip install -r requirements.txt

# 4. Login (stores credentials at ~/.aic/config.json)
python3 aic.py login

# 5. Test
python3 aic.py sub listall

Download aic-cli.zip

Or import as a Python library in your own scripts:

from aic_client import AicClient
client = AicClient()
subs = client.sub_list()
credits = client.sub_credits("submission-id")

API Endpoints

Subscriptions

dev_sub_list

Params: carer_email

List all subscriptions for a carer. Returns subscription_id, cared_for_email, name, status, tier.

python aic.py sub list
python aic.py --json sub listall

dev_sub_status

Params: subscription_id

Full subscription detail: tier, status, emails, carer password, timestamps, Stripe ID.

python aic.py sub status <subscription_id>
python aic.py --json sub status <subscription_id>

dev_sub_credits

Params: subscription_id

Credits remaining: image, video, cartoon — with tier limits, extras, and usage this month.

python aic.py sub credits <subscription_id>
python aic.py --json sub credits <subscription_id>

dev_sub_schedule

Params: subscription_id

Next auto-generated joke date, last joke date, cooldown, overdue flag.

python aic.py sub schedule <subscription_id>
python aic.py --json sub schedule <subscription_id>

dev_sub_pause

Params: subscription_id

Pause a subscription. Jokes stop being auto-generated.

python aic.py sub pause <subscription_id>
python aic.py --json sub pause <subscription_id>

dev_sub_cancel

Params: subscription_id

Cancel a subscription permanently.

python aic.py sub cancel <subscription_id>
python aic.py --json sub cancel <subscription_id>

dev_sub_new

Params: carer_email, cared_for_email, cared_for_name

Flags: tier=premium (basic|standard|premium|group_premium), review=true, above_18=yes, mental_disability=false

Create a new gifted subscription with optional flags. All flags have defaults shown above.

python aic.py sub new
python aic.py sub new --tier standard --review false --above-18 no
python aic.py sub new --tier group_premium --mental-disability true

Jokes & Cartoons

dev_sub_last_jokes

Params: subscription_id, limit (default 10)

Recent jokes with text, presigned image/video URLs (1h expiry), status, source. Use non_expired=true to only return jokes with media.

python aic.py jokes last <subscription_id> --limit 5
python aic.py --json jokes last <subscription_id> --limit 3

dev_joke_feedback

Params: joke_id

All feedback on a joke: liked/disliked sentiment, text comments, humor category, feedback role (carer/cared-for), and source.

python aic.py jokes feedback <joke_id>
python aic.py --json jokes feedback <joke_id>

dev_joke_prompts

Params: joke_id (or subscription_id for last joke)

All ChatGPT and media generation prompts for a joke, including all retry attempts in the thread. Shows prompt text, media generator used, and any rejection/error messages.

python aic.py jokes prompts <joke_id>
python aic.py jokes prompts --sub <subscription_id>
python aic.py --json jokes prompts <joke_id>

dev_joke_generate

Params: subscription_id (or cared_for_email), description, humor_category, tone, media_type

Flags: count_credit=true|false (default: true, false from dev IP), use_face_images=true|false, media_type=image|video

Trigger async joke generation via crack_a_joke. Use dev_sub_last_jokes to check results (generation takes 30-120s). Local image uploads coming soon.

python aic.py jokes generate <subscription_id> --desc "joke about cats" --category dad_jokes --media video
python aic.py --json jokes generate <subscription_id> --desc "spring weather" --media image --no-credit

Advisor

dev_advisor_feedback

Params: subscription_id

Flags: session_id=N (default: last session)

All text entered during a Virtual Joke Advisor session. Shows turns, timestamps, and sources. Defaults to last session if no session_id specified.

python aic.py advisor <subscription_id>
python aic.py advisor <subscription_id> --session 2
python aic.py --json advisor <subscription_id>

Battles

dev_battles

Params: carer_email (optional — filter by carer)

List active battles with group members, consented/opted-out/pending participants, entries submitted, and time remaining.

python aic.py battles list [--carer-email EMAIL]

dev_battle_scores

Params: battle_id (optional — uses most recent if omitted)

Rankings by votes, feedback stats (who gave likes/dislikes), participants, and time remaining.

python aic.py battles scores <battle_id>
python aic.py battles scores
python aic.py --json battles scores

Interactive API Tester

Command

Optional flags

Carer Email (for loading subscriptions)

Existing subscriptions (optional for some commands)

Responses are live from the API. Presigned URLs expire after 1 hour.