Web Service API¶
REST API Endpoints¶
For the currently implemented REST request endpoints available under /api/v1, please refer to the automatically generated backend API documentation as well as the request forms and entity models in our public repository:
- https://pkg.go.dev/github.com/photoprism/photoprism/internal/api
- https://github.com/photoprism/photoprism/tree/develop/internal/api
API request bodies and responses are usually JSON-encoded, except for binary data and some of the OAuth2 endpoints. Note that the Content-Type header must be set to application/json for this, as the request may otherwise fail with error 400.
We welcome any contributions that help improve our API docs and make them easier to use for developers. To learn how to access the API while our Swagger documentation is not complete yet, we recommend checking the requests in the browser console that our JS frontend sends when you perform actions like creating an album - and then use the same method, URI, encoding, value names and types for sending requests with your own application.
Client Authentication¶
When clients have a valid access token, e.g. obtained through the POST /api/v1/session or POST /api/v1/oauth/token endpoint, they can use a standard Bearer Authorization header to authenticate their requests:
Authorization: Bearer <token>
Submitting the access token with a custom X-Auth-Token header is supported as well:
curl -H "X-Auth-Token: 7dbfa37b5a3db2a9e9dd186479018bfe2e3ce5a71fc2f955" \
http://localhost:2342/api/v1/photos?count=10
Besides using the API endpoints provided for this, you can also generate valid access tokens by running the photoprism auth add command in a terminal.
App passwords can be used as access tokens in the Bearer Authorization header without first creating a session access token, and to obtain short-lived session access tokens through the POST /api/v1/session endpoint.
Service Discovery Endpoints¶
OAuth2 Authorization Server¶
/.well-known/oauth-authorization-server
↪ https://demo.photoprism.app/.well-known/oauth-authorization-server
OpenID Configuration¶
It is not yet possible to use PhotoPrism as an OpenID Connect (OIDC) Identity Provider, since not all the required endpoints and grant types have been fully implemented. However, querying the /.well-known/openid-configuration endpoint shows what has already been implemented, so the missing capabilities can be identified and added over time.
↪ https://demo.photoprism.app/.well-known/openid-configuration
Deprecation Policy¶
Our REST API endpoints are currently not covered by an official deprecation policy, so some routes and request parameters may change as we add new features in upcoming releases.
However, we avoid making breaking changes, especially to endpoints that we know other developers are using.