API access

Use the management API

Applies to 2026.10.19. This release protects management API reads and writes when Basic Auth or OIDC is configured. OIDC browser login does not authorize management API calls.

Choose the correct credentials

Installation	Management API behavior
Both BASIC_AUTH_USERNAME and BASIC_AUTH_PASSWORD configured	Send those credentials with HTTP Basic Auth.
OIDC enabled, no Basic Auth credentials	Management API requests are rejected. Configure both Basic Auth variables for API clients; the browser continues using OIDC.
Only one Basic Auth variable configured	Management API access is rejected. Configure both or remove the incomplete configuration.
Neither OIDC nor Basic Auth configured	The app does not require management API credentials. Network exposure still follows your deployment configuration.

Set credentials using your existing secret-management method, then recreate the application container. See Environment variables and OIDC single sign-on.

Make a read-only request

Interactive API documentation is at /api/docs; the specification is at /api/spec. Adjust the host and deployment prefix in this example:

curl --user 'YOUR_USERNAME' \
  --header 'Accept: application/json' \
  'https://pinchflat.example.com/api/media/recent_downloads?limit=10'

curl prompts for the password rather than putting it in the example command. Use HTTPS across untrusted networks. A successful request returns JSON; 401 means the app did not accept the supplied credentials. A browser session cookie or a scoped share token does not substitute for Basic Auth here.

Separate routes have separate access rules

• /healthcheck and /api/spec remain public.
• /api/share/intake uses a profile-bound Bearer token. See sharing and bookmarklets.
• Podcast feeds and streaming retain their existing Basic Auth/exposure/route-token behavior. Enabling feed exposure does not make the management API public.
• Browser forms still use their normal browser authentication and CSRF protection. Do not reuse internal form action URLs as management API endpoints.

During legacy or PostgreSQL migration review, management API writes are held with 423 until the required review is completed. Authentication still applies to reads. See SQLite-to-PostgreSQL migration or Migrating from Pinchflat.

Check outcomes, not only request submission

Queue actions distinguish accepted work, duplicates and failures. A successful enqueue is not a completed download; batch operations can report partial failure with 503. Read the returned outcomes and inspect Diagnostics before retrying a whole batch. Use download recovery for failed media.

All feature guides