---
title: "Developer portal — SocialShot AI API"
canonical: https://socialshot.ai/developers
description: "SocialShot AI API: public endpoints, authentication, rate limits, versioning and deprecation policy, OpenAPI specification."
site: "SocialShot AI"
---

# SocialShot AI developer portal

SocialShot AI has two API surfaces: a public, unauthenticated discovery API on the apex domain, and the authenticated platform API that backs the product.

## Quickstart

```bash
curl -s https://socialshot.ai/api/v1 | jq
curl -s https://socialshot.ai/api/v1/tools | jq '.data[].name'
curl -s https://socialshot.ai/api/v1/plans | jq
```

No key, no signup, no rate-limit registration needed.

## Public API

Base URL: `https://socialshot.ai/api/v1`

| Method | Endpoint | Auth | Description |
| --- | --- | --- | --- |
| GET | `/api/v1` | none | Discovery document: every endpoint, policies, when-to-use guidance |
| GET | `/api/v1/status` | none | Service status and version |
| GET | `/api/v1/tools` | none | Capability catalogue with inputs and outputs |
| GET | `/api/v1/plans` | none | Plans, prices and credits |

OpenAPI 3.1 description: https://socialshot.ai/openapi.json

RFC 9727 API catalog: https://socialshot.ai/.well-known/api-catalog

## Platform API

Base URL: `https://api.socialshot.ai`

- Full generated OpenAPI: https://api.socialshot.ai/openapi.json
- Interactive reference: https://api.socialshot.ai/docs

Publicly reachable, unauthenticated endpoints on the platform API:

- `GET https://api.socialshot.ai/api/health` — health and provider capability flags
- `GET https://api.socialshot.ai/api/marketplaces` — per-marketplace image specs (required pixel dimensions, background and framing rules) for Amazon, Flipkart, Myntra, Meesho, Ajio and Nykaa
- `GET https://api.socialshot.ai/api/legal/documents` — published legal documents

## Authentication

- Public discovery endpoints: **no authentication**. Do not send a token.
- Platform API: `Authorization: Bearer <token>` where the token is the JWT from a signed-in session (Clerk).
- **Programmatic API keys are not yet issued.** There is no way today to run a generation unattended from a server. If you need this, email hello@socialshot.ai and say what you are building — it is on the roadmap and we are prioritising by real use case.

## Rate limits

120 requests per 60 seconds per client IP on the public API.

Every response carries:

```http
RateLimit-Policy: "public";q=120;w=60
RateLimit: "public";r=119;t=53
RateLimit-Limit: 120
RateLimit-Remaining: 119
RateLimit-Reset: 53
```

`RateLimit-Policy` and `RateLimit` are the structured fields from draft-ietf-httpapi-ratelimit-headers (`q` quota, `w` window seconds, `r` remaining, `t` seconds to reset). The `RateLimit-Limit` / `-Remaining` / `-Reset` triple is emitted alongside them for older clients. A 429 adds `Retry-After` in delta-seconds.

## Versioning and deprecation

- Scheme: url-path. Current version: `v1`.
- Additive changes (new fields, new endpoints, new enum members) can ship at any time without a version bump. Clients MUST ignore unknown fields.
- Removing or renaming a field, changing a field's type, or changing the meaning of an existing value requires a new major version at a new URL path (/api/v2/...). /api/v1 keeps working while it is supported.
- A deprecated endpoint returns the Deprecation and Sunset response headers (RFC 9745 / RFC 8594) plus a Link header with rel="deprecation" pointing at the migration notes. Deprecation carries the date the deprecation was announced; Sunset carries the date the endpoint stops responding.
- At least 180 days between the Deprecation header first appearing and the Sunset date.
- Nothing is deprecated today, so no endpoint currently sends those headers.

## Markdown content negotiation

Every public page has a markdown representation. Ask for it with an `Accept` header, or by appending `.md`:

```bash
curl -H "Accept: text/markdown" https://socialshot.ai/pricing
curl https://socialshot.ai/pricing.md
```

Responses carry `Content-Type: text/markdown; charset=utf-8` and `Vary: Accept`, per acceptmarkdown.com. A client that explicitly refuses both HTML and markdown gets a `406`.

## Not available yet

- **Virtual try-on widget** — Feature flag off
- **UGC / product / cinematic video** — Admin-gated, in development
- **Programmatic API keys** — Not yet issued — contact us

## Support

- Email: hello@socialshot.ai
- Contact form: https://socialshot.ai/contact