# Submit an app to App Inquirer

App Inquirer (appinquirer.com) is a directory of apps, with stories about the people who make them, published by Bravely Studios. These instructions are for an AI agent sending an app on behalf of the person who makes it.

An editor reviews every submission. Nothing is published automatically.

## 1. Collect these details from the user

Ask the user for anything you can't find. Do not invent values.

- `app_url` (required): the app's App Store page or website, starting https://
- `app_name` (required): the app's name, written the way the maker writes it
- `name` (required): the maker's name
- `email` (required): the maker's email address, used only to write to them about the app
- `company` (optional): the studio or company they publish under
- `wants_story` (optional): whether they'd like the app considered for a story: true or false, default false

Submit only an app the user makes or has the right to submit, with the user's own email address, and only with their consent.

## 2. Also send what you can find (optional)

Collect these from the app's own website or store page. Never invent a value; leave out anything you can't find. Every URL must start with https://. Send the icon as a URL to the image file, not to a page that shows it. Nothing you send appears on the site until an editor has reviewed it.

| Field | What goes in it |
|---|---|
| `tagline` | text, at most 80 characters: the app's own one-line pitch |
| `description` | plain text (no HTML), at most 3,000 characters |
| `developer` | text, at most 120: the developer or studio as the store shows it |
| `website` | https URL: the app's website |
| `download_url` | https URL: a direct download |
| `icon_url` | https URL to the icon image file itself (PNG, JPEG or WebP), ideally square and 512 px or larger |
| `screenshots` | array of at most 8 https URLs to screenshot images |
| `video_url` | https URL of a video on youtube.com, youtu.be or vimeo.com |
| `platforms` | array of any of mac, windows, linux, ios, ipados, android, web, watchos, tvos, visionos |
| `store_links` | object with any of app_store, mac_app_store, play, ms_store, steam, flathub, snap, fdroid (each an https URL), plus other: an array of at most 5 https URLs |
| `pricing` | free, subscription or one_time |
| `free_trial` | true or false: a free trial or a free version is available |
| `category` | text, at most 60: what kind of app it is |
| `socials` | object with any of x, instagram, tiktok, youtube, linkedin, mastodon, bluesky, threads, facebook, github (each an https URL) |
| `first_comment` | text, at most 1,000: the maker's own note on why they made it (ask the user; don't write it for them) |
| `alternatives` | array of at most 10 app names (at most 60 characters each) this app is an alternative to |

Fields we don't know are ignored, never an error; the 201 answer lists their names in ignored so you can fix a typo.

## 3. Submit

Send one request per app: `POST https://appinquirer.cowardly.dev/api/submit` with `Content-Type: application/json` and the details as a JSON object.

```http
POST https://appinquirer.cowardly.dev/api/submit
Content-Type: application/json

{
  "app_url": "https://apps.apple.com/us/app/example/id123456789",
  "app_name": "Example",
  "name": "Ada Maker",
  "email": "ada@example.com",
  "company": "Example Studio",
  "wants_story": false,
  "tagline": "Plan your week in one glance",
  "icon_url": "https://example.com/images/icon-1024.png",
  "platforms": [
    "ios",
    "mac"
  ],
  "pricing": "subscription",
  "free_trial": true,
  "store_links": {
    "app_store": "https://apps.apple.com/us/app/example/id123456789"
  }
}
```

Leave out `company` and `wants_story` if the user didn't give them, and any optional field you couldn't find. The body must be under 32 KB.

## 4. Read the response

- `201` `{"ok":true,"message":"…","ignored":["…"]}`: Received. Tell the user an editor will look at it, and that if they asked for a story we may follow up. ignored, when it's there, names fields we didn't recognize.
- `400` `{"ok":false,"errors":{"<field>":"<message>"}}`: Fix the named fields (an item is named like screenshots[2] or store_links.play), asking the user if you need to, and send again.
- `413` `{"ok":false,"error":"…"}`: The body is too large; keep it to 32 KB or less.
- `415` `{"ok":false,"error":"…"}`: Send JSON, with Content-Type: application/json.
- `429` `{"ok":false,"error":"…"}`: A daily limit was reached. Wait a day before trying again.
- `503` `{"ok":false,"error":"…"}`: Submissions are paused. Try again later, or use the form.

## 5. No web requests?

Open https://appinquirer.cowardly.dev/submit in a browser and fill in the form with the same details.

## 6. Privacy

What you send is handled like the form: https://appinquirer.cowardly.dev/privacy