# diaspora*

> diaspora* is a privacy-aware, decentralized, open source social network released under the AGPL. It runs as a federation of independently operated servers called "pods" rather than on servers owned by a single company. Since release 0.9.0.0 the project officially supports third-party applications through a documented JSON REST API at /api/v1 on every pod, authenticated with OpenID Connect.

<!--
generated: 2026-07-20
method: generated
source: Generated by the API Evangelist enrichment pipeline from apis.yml and the artifacts in this repository. The diaspora* project does not publish an llms.txt — https://diasporafoundation.org/llms.txt, https://diaspora.github.io/api-documentation/llms.txt and https://diaspora.software/llms.txt all returned HTTP 404 on 2026-07-20. Facts below come from the official documentation at https://diaspora.github.io/api-documentation/ and from live probes.
-->

## What an integrator most needs to know

- **There is no single API host.** Every pod serves the same API under its own domain at `/api/v1`. `https://diaspora.social/api/v1` is one pod among many, not a canonical endpoint. A client must be told which pod the user belongs to.
- **Discover before you call.** Read `/.well-known/nodeinfo` on the target pod to confirm it runs a release that supports API v1. Read `/.well-known/openid-configuration` to find its OAuth endpoints.
- **Register yourself at runtime.** Because an application cannot be pre-registered on every pod, diaspora* implements OpenID Connect Dynamic Client Registration: POST `client_name` and `redirect_uris` to `/api/openid_connect/clients` and receive a `client_id` and `client_secret` for that pod.
- **Every endpoint requires authentication.** No token or an invalid token returns `401`. A valid token missing the endpoint's scope returns `403` with an empty body.
- **JSON only.** Send `Accept: application/json`, or append `.json` to the URL.

## Authentication

- [Authentication](https://diaspora.github.io/api-documentation/authentication.html): OpenID Connect Core 1.0, Authorization Code Flow (native apps) or Implicit Flow (browser apps), with Discovery 1.0 and Dynamic Client Registration 1.0. ID tokens are signed RS256. Tokens are sent as `Authorization: Bearer <token>`.
- [Access scopes](https://diaspora.github.io/api-documentation/scopes.html): 16 scopes. `openid` is mandatory. `public:read` is always granted and cannot be opted out of. `private:read` and `private:modify` can only be granted alongside `contacts:read`. Granted scopes may differ from requested scopes.

## API surface

62 documented operations across 14 resource groups. Full description: [OpenAPI](openapi/diaspora-api-openapi.yml).

- [Posts](https://diaspora.github.io/api-documentation/routes/posts.html): publish, fetch and delete posts. A post may embed photos, a poll, a location, OpenGraph metadata, oEmbed metadata, mentioned people, and — for reshares — a `root` object describing the original.
- [Comments](https://diaspora.github.io/api-documentation/routes/comments.html): list, add, delete and report comments on a post.
- [Likes](https://diaspora.github.io/api-documentation/routes/likes.html): like and unlike posts and comments.
- [Reshares](https://diaspora.github.io/api-documentation/routes/reshares.html): reshare a public post; list reshares.
- [Post interactions](https://diaspora.github.io/api-documentation/routes/post_interactions.html): report, subscribe, mute, hide, and vote in polls.
- [Aspects](https://diaspora.github.io/api-documentation/routes/aspects.html): create, rename, reorder and delete aspects — the contact groups that determine who sees private posts.
- [Contacts](https://diaspora.github.io/api-documentation/routes/contacts.html): list aspect membership; add and remove people.
- [Conversations](https://diaspora.github.io/api-documentation/routes/conversations.html): private messaging — threads and messages.
- [Notifications](https://diaspora.github.io/api-documentation/routes/notifications.html): list notifications and mark them unread.
- [Photos](https://diaspora.github.io/api-documentation/routes/photos.html): upload, list, fetch and delete photos, served in raw/large/medium/small sizes.
- [Streams](https://diaspora.github.io/api-documentation/routes/streams.html): main, aspects, activity, mentions, tags, liked and commented timelines.
- [Search](https://diaspora.github.io/api-documentation/routes/search.html): users, posts and tags.
- [Tag followings](https://diaspora.github.io/api-documentation/routes/tag_followings.html): list, follow and unfollow hashtags.
- [Users](https://diaspora.github.io/api-documentation/routes/users.html): read and update the authenticated profile, look up other users, block and unblock.

## Conventions

- **Identifiers**: federated entities (people, posts, comments, photos, conversations, polls) use network-wide 32-character hex GUIDs. Pod-local entities (aspects, notifications, poll answers) use integer ids. Tag followings are keyed by tag name.
- **Timestamps**: ISO 8601 with timezone, e.g. `2016-02-19T02:13:41.863Z`.
- **Pagination**: signalled by a `Link` header with `rel` values `first`, `previous`, `next`, `last`. `per_page` defaults to 20 and is capped at 100. Do not construct pagination URLs — some resources page by timestamp or GUID rather than an integer counter.
- **Errors**: a bespoke `{"code": <int>, "message": <string>}` envelope served as `application/json`. This is **not** RFC 9457, and there is no stable machine-readable error identifier — branch on HTTP status plus the operation you called, never on message text.
- **Idempotency**: not supported. There is no idempotency key header. However, interaction endpoints return `409` when the thing already exists and `410` when it does not, so likes, reshares, blocks, tag followings and subscriptions converge safely on retry.
- **Rate limiting**: not documented. Pods are volunteer-operated; self-limit rather than assume capacity.
- **`404` may mean "not visible to you"** rather than "does not exist", because visibility is governed by aspects and by federation reach.

## Versioning and support

- API version `v1`, path-prefixed at `/api/v1`. It is the only version ever shipped and became officially supported in release 0.9.0.0 (2024-06-16).
- The documentation index still shows a banner saying the API is unstable pending release 0.8.0.0. **That banner is stale** — treat it as an unmaintained document.
- Supported versions for security fixes: the latest stable release and the current `develop` branch. Older releases are out of scope.
- No SLA and no official status page — there is no central operator. Community pod uptime data is at https://diaspora.fediverse.observer/.
- Vulnerability disclosure: security@diasporafoundation.org, PGP `AB0D AB02 0FC5 D398 03AB 3CE1 6F70 243F 27AD 886A`.

## Libraries

The project publishes no client SDK for its own REST API in any language — use a standard OpenID Connect library plus plain HTTP. The first-party packages that do exist are federation-protocol libraries for building pods: `diaspora_federation`, `diaspora_federation-rails`, `diaspora_federation-test` and `diaspora_federation-json_schema` on RubyGems, plus `markdown-it-diaspora-mention` on npm for rendering mention syntax.

## Optional

- [Project site](https://diasporafoundation.org/)
- [API documentation](https://diaspora.github.io/api-documentation/)
- [Wiki](https://wiki.diasporafoundation.org/Main_Page)
- [Discourse community and API support](https://discourse.diasporafoundation.org/)
- [Blog](https://blog.diasporafoundation.org/)
- [GitHub organization](https://github.com/diaspora)
- [Changelog](https://github.com/diaspora/diaspora/blob/develop/Changelog.md)
- [Pod directory](https://diaspora.fediverse.observer/)