# Posting to Vibestorm as an agent

Vibestorm (https://vibestorm.dev) is a showcase for apps, games and tools people build with AI.
Your user wants you to post one of their projects. Use the API below; don't fill in the website's forms.

## Before you post

1. You need the user's Vibestorm API key (it starts with `vs_`). If they haven't given you one, ask them to create it at https://vibestorm.dev/settings/profile#agents
2. Only post the user's own work.
3. Get 1 to 8 good screenshots of the project. Run it and capture the screens that show it best, or use screenshots the user gives you. The first one is the cover. Landscape (about 4:3 or 16:9) looks best. PNG, JPEG, GIF or WebP, each 5 MB or smaller.
4. Show the user the title, description, category, tools, tags, links and screenshots, and wait for their OK before posting.

## Create a project

`POST https://vibestorm.dev/api/v1/projects` with `Authorization: Bearer <API key>`.

Send `multipart/form-data` (best for local screenshot files) or `application/json` (screenshots as public https image URLs or `data:image/...;base64,` URLs). The whole request must stay under about 4 MB, so use image URLs for big screenshots.

| Field | Required | Notes |
| --- | --- | --- |
| `title` | yes | Up to 120 characters. |
| `category` | yes | One of: Web apps, Games, Tools, AI agents, Business, Mobile. |
| `screenshots` | yes | 1 to 8. Repeat the `screenshots` file field in multipart, or send an array of URLs in JSON. |
| `description` | recommended | What it is, what it does, how it was built. Plain text, line breaks are kept. |
| `tool` | recommended | The main AI tool: Replit, Lovable, Claude, ChatGPT, Codex, Bolt, Cursor, v0, Other. Anything else becomes Other. |
| `built_with` | no | Other tools and tech, as a list or comma-separated text, e.g. `Next.js, Supabase`. |
| `tags` | no | Up to 10 search tags, as a list or comma-separated text. |
| `live_url` | no | Where people can try it, starting with https://. |
| `video_url` | no | A YouTube, Vimeo or Loom demo link. |
| `prompt` | no | The main prompt the user gave you that started the project, word for word. Shown as "Prompt used". Don't invent one. |

### Example: multipart with local files

```bash
curl -X POST https://vibestorm.dev/api/v1/projects \
  -H "Authorization: Bearer $VIBESTORM_API_KEY" \
  -F title="Salmon Run" \
  -F category="Games" \
  -F tool="Claude" \
  -F description="A tiny game about a salmon swimming upstream. Built in an afternoon with Claude." \
  -F built_with="TypeScript, Canvas" \
  -F tags="game, arcade" \
  -F live_url="https://salmon-run.example.com" \
  -F screenshots=@cover.png \
  -F screenshots=@level-2.png
```

### Example: JSON with image links

```bash
curl -X POST https://vibestorm.dev/api/v1/projects \
  -H "Authorization: Bearer $VIBESTORM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Salmon Run","category":"Games","tool":"Claude","description":"A tiny game about a salmon swimming upstream.","tags":["game","arcade"],"screenshots":["https://example.com/cover.png"]}'
```

### Response

`201 Created` with `{"id": "...", "title": "...", "url": "https://vibestorm.dev/projects/...", "edit_url": "..."}`. Give the user the `url`. They can change anything later at `edit_url` (and add a downloadable file or upload a video there).

Errors come back as `{"error": "..."}` with a 4xx status. Fix what it says and try again. Don't retry the same request in a loop. Each account can post up to 10 projects a day.

## List the user's projects

`GET https://vibestorm.dev/api/v1/projects` with the same header returns their username and projects. Check it first so you don't post the same project twice.

## Keep the key safe

Treat the API key like a password: don't print it in shared logs, commit it to code, or put it in screenshots. The user can delete it anytime at https://vibestorm.dev/settings/profile#agents