API reference

Get an API key

Every endpoint of Sofia API v1 with its parameters, scopes and examples, and a playground to try each one with your own API key.

Base URL https://api.sofia-post.com/api · OpenAPI document

OAuth

GET/v1/oauth/authorizeStart an authorizationOpen it in the browser of the person. An unknown client or unregistered redirect_uri gives a 400; otherwise it redirects to Sofia consent screen.GET/.well-known/oauth-authorization-server/api/v1/oauthGet server metadataReturns the OAuth 2.0 authorization server metadata of the Sofia API (RFC 8414), so a client can discover the endpoints and the supported options.POST/v1/oauth/tokenIssue an access tokenExchanges client_credentials, an authorization_code with PKCE or a single-use refresh_token for an opaque token valid 3600 seconds for one Workspace.

Account

GET/v1/meWho am IDescribes the calling token: its kind, application, the person it acts for, their Workspaces, scopes, mode and expiry. Any valid token can read it.

Platforms

GET/v1/platformsList platformsLists each network with its caption, media and format rules, the same ones the sandbox and dry run apply, and whether it is open to the token owner.

Establishments

GET/v1/establishmentsList establishmentsLists the establishments of the Workspace the token acts on. Use their identifiers as establishmentId when you publish, list media or read insights.GET/v1/establishments/{id}/accountsList connected accountsLists the networks connected to an establishment, with no token or network secret, only what you need to name an account and pick it as accountId.POST/v1/establishments/{id}/connection-linksCreate a connection linkReturns a hosted link where the person authorizes a network with Sofia, so no network token reaches your app. Valid 30 minutes; live app only.GET/v1/establishments/{id}/insightsGet establishment insightsReturns the latest valid figures Sofia collected for each connected account. An account not yet collected reads awaiting, never zero.

Media

GET/v1/mediaList mediaLists the media library of an establishment, newest first, page by page, with URLs signed for the current window. Works in test and live.POST/v1/mediaImport or upload a mediaAdds a file (multipart) or an https URL that Sofia fetches to the media library of an establishment. Needs a live application and an active subscription.GET/v1/media/{id}Get a mediaReturns one media of the library with a signed URL valid for the current window, so you can reuse its identifier in a post.DELETE/v1/media/{id}Remove a mediaRemoves a media from the library of its establishment, as the app does. The file is not destroyed and a scheduled post keeps its visual.

Posts

GET/v1/postsList postsLists the posts of the establishments in reach of the token, newest first, filtered by establishment, status, date window and author, page by page.POST/v1/postsPublish a postLive apps publish at once, schedule with a date or save a draft; test apps only simulate. With ?dry_run=true it checks everything and writes nothing.GET/v1/posts/{id}Get a postReturns a post with the state of each network, its link once published and its error if it failed. Live reads any post of the Workspace, test a simulated one.PATCH/v1/posts/{id}Edit a postBefore any network has started sending, replaces targets, sets scheduledAt or moves the post between draft and scheduled. Omitted fields are kept.DELETE/v1/posts/{id}Delete a postDeletes a post as the app does: nothing scheduled is sent and a published post is removed from its network. Test applications have nothing real to delete.

Webhooks

GET/v1/webhooksList webhooksLists the webhooks of the application without their signing secret, which is only returned when the webhook is registered.POST/v1/webhooksRegister a webhookRegisters an https URL that Sofia calls with a signed JSON event, retried up to five times on failure. The secret is shown once; 10 webhooks at most.DELETE/v1/webhooks/{id}Delete a webhookDeletes a webhook. It receives nothing more, not even the deliveries that were still waiting for a retry, and the call returns no body.POST/v1/webhooks/{id}/testSend a test eventDelivers a signed webhook.test event like any other, without waiting for the receiver, so you can check your signature. At most five per minute.