Developer and agent reference

What OriginShot is

OriginShot turns a single smartphone photo into a complete, Etsy-ready listing: a background-composited image at Etsy's recommended resolution, an SEO title, exactly 13 tags and a two-paragraph description. It serves Etsy sellers of handmade, vintage and small-batch goods. Pixel-Lock Compositing keeps every original product pixel unchanged, so the listing image still represents the item that is sold.

API status

There is no public write API today. Generation runs only inside the signed-in web application. Every route that spends credits, reads a listing, or touches account or billing data needs a session cookie and a verified email address, and mutating routes also need a CSRF token. A smaller set is exempt from the session gate and is authenticated another way: the sign-in and registration endpoints, the CSRF token endpoint, the client log sink, the provider webhooks (verified by signature), the scheduled jobs (verified by a bearer token) and the health probes. An unauthenticated request to a protected route gets 401 and a JSON body, never an HTML page.

If you need programmatic access, write to us and describe what you want to build.

Machine-readable resources

These four files describe the site to a program. They need no authentication and no JavaScript.

• /llms.txt — Product summary, when to use OriginShot, and an index of every public page
• /openapi.json — OpenAPI 3.1 description of the endpoints that answer without a session
• /sitemap.xml — Every indexable page, with a fixed last-modified date
• /robots.txt — Crawl policy, stated per user agent

Markdown instead of HTML

Send Accept: text/markdown and the main marketing pages answer with a markdown summary instead of HTML. The response carries Vary: Accept, so a cache cannot serve the wrong variant. Pages with no markdown form answer with HTML as usual.

curl -H "Accept: text/markdown" https://originshot.com/

Error format

Every error response uses the same JSON shape and a 4xx or 5xx status. The value of errorKey is a stable identifier, not a human message, so a client can branch on it without reading prose. The two fields always hold the same value; error is kept for older clients.

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "error": "authErrors.unauthorized",
  "errorKey": "authErrors.unauthorized"
}

Rate limits

Every API route is rate limited per client and per route. The limit differs by route. A successful response states the policy only. A refused response adds the live counters and the time to wait. Do not probe for the counters: count your own requests and stay inside the policy.

HTTP/1.1 200 OK
RateLimit-Policy: 20;w=60
X-RateLimit-Limit: 20

HTTP/1.1 429 Too Many Requests
RateLimit-Policy: 20;w=60
X-RateLimit-Limit: 20
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1793577600
Retry-After: 43

• RateLimit-Policy — The limit and the window length, for example 20;w=60 for 20 requests each 60 seconds.
• X-RateLimit-Limit — Requests allowed in the current window.
• X-RateLimit-Remaining — Requests left in the current window. Sent with a 429 only, to avoid publishing the state of a shared bucket to an anonymous caller.
• X-RateLimit-Reset — Unix time in seconds when the window resets. Sent with a 429 only.
• Retry-After — Seconds to wait before you retry. Sent only with a 429 response.

Crawler and AI agent policy

AI agents are welcome on the marketing pages, the guides and the machine-readable files. Reading and quoting this content is permitted. The dashboard, the API and /private are closed to every agent, and a session cookie protects them independently of robots.txt. The named agents and the exact paths are in the robots file.

Contact

Write to us about programmatic access, a wrong response, or anything else on this page.

hello [at] originshot.comContact page