REST API v1

API changelog

What changed in the API and when, newest first, and the rules for announcing changes that could break your client.

OpenAPI spec (openapi.json) API Terms of Use

Deprecation policy

  • Changes that break compatibility (removing or renaming a field or an endpoint, changing the meaning of a field, tightening validation of an existing field) will be announced in this changelog no later than 90 days before they take effect.
  • A field or an endpoint will not be removed without a deprecation period. During it the field or endpoint keeps working and is marked as deprecated in the documentation and in openapi.json.
  • Deprecated endpoints will answer with the Deprecation response header, and with a Sunset header carrying the date of removal once that date is known.
  • Additive changes (a new endpoint, a new optional field, a new value in a response) are not breaking. Write your client so that it ignores fields it does not know.

The rules for using the API are in the API Terms of Use; endpoints and limits are in the developer guide.

Changes

  1. Hardening of the public API

    v1.7
    • Attachment and upload image URLs are accepted only from pixPLace’s own storage host and the documented public hosts; other *.supabase.co and *.supabase.in hosts are no longer accepted. Use POST /api/v1/uploads/from-url or POST /api/v1/uploads to get an accepted URL.
    • The limits section of the documentation describes limits by numbers only.
    • GET /api/v1/categories returns category names with HTML entities decoded.
    • Example identifiers in the documentation and in openapi.json are synthetic placeholders.

  2. Machine-readable spec and developer documentation

    v1.6
    • GET /api/v1/openapi.json: the OpenAPI 3.1 description of the whole API, generated from the same endpoint list as the documentation.
    • The developer guide at /developers, with quick start, endpoints, limits and error codes.
    • The page /llms.txt describes pixPLace for language models.

  3. Social API: comments and account

    v1.5
    • GET /api/v1/posts/{id}/comments and POST /api/v1/posts/{id}/comments: read and write comments on a post.
    • GET /api/v1/comments: the inbox of comments on your posts. DELETE /api/v1/comments/{id}: delete a comment.
    • GET /api/v1/account and GET /api/v1/account/stats: your account and its statistics per UTC day.
    • GET /api/v1/followers, GET /api/v1/following and GET /api/v1/notifications, and POST /api/v1/notifications/read.

  4. Social API, phase A: manage your own posts and stories

    v1.4
    • GET /api/v1/posts/{id}, PATCH /api/v1/posts/{id} and DELETE /api/v1/posts/{id} for your own posts.
    • Statistics per day for a post.
    • DELETE /api/v1/stories/{id} for your own stories.

  5. Niches

    v1.3
    • GET /api/v1/niches: the taxonomy of niches, public, no key needed.
    • POST /api/v1/posts uses a default niche category when you send none.

  6. Stories API

    v1.2
    • POST /api/v1/stories and GET /api/v1/stories: publish and list stories with an API key.

  7. Media upload

    v1.1
    • POST /api/v1/uploads/from-url: the server downloads a public URL and returns a pixPLace media URL; requests to private or internal addresses are refused.
    • POST /api/v1/uploads: a presigned upload for larger files.

  8. Posts API

    v1.0
    • POST /api/v1/posts with a carousel of attachments (attachments[]), deep links and SEO keywords.
    • The Idempotency-Key header: a repeat with the same key returns the original post instead of a duplicate.
    • Rate limits answer 429 with a Retry-After header.

Planned

Not available yet. Listed so you know what is being considered; there is no date, and nothing here is part of the API today.

  • API key scopes

    planned
    • Scopes would let a key be limited to the operations it needs. Not available yet: today a key can use every operation of its own account.