{"openapi":"3.0.3","info":{"title":"dPoster API","version":"1.0.0","description":"Connect a Facebook Page, set a posting strategy, and let our AI generate and publish content — all callable from your own app. Start at /developer to create a key."},"servers":[{"url":"https://app.digents.com/api/v1"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"A Digents API key, e.g. `digents_sk_test_...` (sandbox) or `digents_sk_live_...` (production)."}}},"paths":{"/me":{"get":{"operationId":"getMe","summary":"Identify this key","description":"The first call any integration should make: confirms the key works and which environment and account it belongs to.","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":{"environment":"production","account_email":"owner@example.com","pages_connected":1}}}}},"401":{"description":"unauthorized — the key is missing, malformed, or revoked","content":{"application/json":{"example":{"error":{"code":"unauthorized","message":"the key is missing, malformed, or revoked"}}}}}}}},"/connect-link":{"post":{"operationId":"createConnectLink","summary":"Get a Facebook connect link","description":"Returns a one-time link, valid 15 minutes, that lets the Page owner connect Facebook directly — no dPoster account or login on their part. The Page ends up connected to YOUR account, the one this key belongs to. Hand the link to whoever administers the Facebook Page. Optional body: `{ \"return_url\": \"https://…\" }` (https, at most 500 characters) — once Facebook is done the owner is sent back there with `connected=1`, or `connected=0&reason=denied|expired|facebook_failed`, instead of staying on our success page. The return address is signed into the link, so it can't be edited.","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object"},"example":{"return_url":"https://yourapp.example/settings/facebook"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":{"url":"https://app.digents.com/connect?ct=xxxxxxxx","expires_at":"2026-09-13T21:15:00.000Z"}}}}},"400":{"description":"invalid_body — `return_url` is not an https URL of at most 500 characters","content":{"application/json":{"example":{"error":{"code":"invalid_body","message":"`return_url` is not an https URL of at most 500 characters"}}}}},"401":{"description":"unauthorized — the key is missing, malformed, or revoked","content":{"application/json":{"example":{"error":{"code":"unauthorized","message":"the key is missing, malformed, or revoked"}}}}}}}},"/pages":{"get":{"operationId":"listPages","summary":"List connected Pages","description":"Every Facebook Page connected to this account, with its posting strategy if one has been set.","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":[{"id":"b6f2...","page_id":"101587169481464","page_name":"Haat Bazaar & Butcher Shop","instagram_username":"haatbazaarhalal","strategy":{"mode":"review","is_paused":false,"tone":"casual"}}]}}}},"401":{"description":"unauthorized — the key is missing, malformed, or revoked","content":{"application/json":{"example":{"error":{"code":"unauthorized","message":"the key is missing, malformed, or revoked"}}}}}}}},"/pages/{pageId}/strategy":{"get":{"operationId":"getPageStrategy","summary":"Read a Page's strategy","description":"The niche, tone, schedule, and posting mode our AI uses for this Page. `null` if none has been set yet.","security":[{"bearerAuth":[]}],"parameters":[{"name":"pageId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":{"niche":"Grocery","tone":"casual","mode":"review","is_paused":false}}}}},"401":{"description":"unauthorized — the key is missing, malformed, or revoked","content":{"application/json":{"example":{"error":{"code":"unauthorized","message":"the key is missing, malformed, or revoked"}}}}},"404":{"description":"not_found — no Page with that id on this account","content":{"application/json":{"example":{"error":{"code":"not_found","message":"no Page with that id on this account"}}}}}}},"put":{"operationId":"updatePageStrategy","summary":"Set or update a Page's strategy","description":"Partial updates are fine — only the fields you send change. The first call for a Page must include at least `niche`, `business_description`, and `target_audience`. `posting_frequency`, `preferred_time`, and `timezone` are saved but not applied yet: the daily automation makes at most one post per Page per day, when it runs during the 09:00 UTC hour.","security":[{"bearerAuth":[]}],"parameters":[{"name":"pageId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object"},"example":{"niche":"Halal grocery & butcher shop","business_description":"A neighborhood halal grocery known for fresh-cut meat and weekly specials.","target_audience":"Families in the local Muslim community","tone":"casual","posting_frequency":1,"preferred_time":"09:00","timezone":"America/New_York","mode":"review"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":{"page_id":"b6f2...","niche":"Halal grocery & butcher shop","mode":"review"}}}}},"400":{"description":"missing_fields — this Page has no strategy yet and a required field is missing","content":{"application/json":{"example":{"error":{"code":"missing_fields","message":"this Page has no strategy yet and a required field is missing"}}}}},"401":{"description":"unauthorized — the key is missing, malformed, or revoked","content":{"application/json":{"example":{"error":{"code":"unauthorized","message":"the key is missing, malformed, or revoked"}}}}},"404":{"description":"not_found — no Page with that id on this account","content":{"application/json":{"example":{"error":{"code":"not_found","message":"no Page with that id on this account"}}}}}}}},"/pages/{pageId}/pause":{"post":{"operationId":"pausePage","summary":"Pause a Page","description":"Stops the daily automation for this Page until resumed. Creating drafts and publishing through this API still work while a Page is paused — so pausing is how a Page posts only when you ask it to.","security":[{"bearerAuth":[]}],"parameters":[{"name":"pageId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":{"page_id":"b6f2...","is_paused":true}}}}},"400":{"description":"no_strategy — this Page has no strategy yet","content":{"application/json":{"example":{"error":{"code":"no_strategy","message":"this Page has no strategy yet"}}}}},"401":{"description":"unauthorized — the key is missing, malformed, or revoked","content":{"application/json":{"example":{"error":{"code":"unauthorized","message":"the key is missing, malformed, or revoked"}}}}},"404":{"description":"not_found — no Page with that id on this account","content":{"application/json":{"example":{"error":{"code":"not_found","message":"no Page with that id on this account"}}}}}}}},"/pages/{pageId}/resume":{"post":{"operationId":"resumePage","summary":"Resume a Page","description":"The inverse of /pause.","security":[{"bearerAuth":[]}],"parameters":[{"name":"pageId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":{"page_id":"b6f2...","is_paused":false}}}}},"400":{"description":"no_strategy — this Page has no strategy yet","content":{"application/json":{"example":{"error":{"code":"no_strategy","message":"this Page has no strategy yet"}}}}},"401":{"description":"unauthorized — the key is missing, malformed, or revoked","content":{"application/json":{"example":{"error":{"code":"unauthorized","message":"the key is missing, malformed, or revoked"}}}}},"404":{"description":"not_found — no Page with that id on this account","content":{"application/json":{"example":{"error":{"code":"not_found","message":"no Page with that id on this account"}}}}}}}},"/pages/{pageId}/drafts":{"post":{"operationId":"createDraftPost","summary":"Create a draft post","description":"Send `topic` and the AI writes the caption (and an image, if enabled). Or send your own `caption` — and optionally your own `image_url`, e.g. a product photo — to skip AI generation and use your content verbatim. Either way the draft passes the same safety checks as the dashboard. A Page with no strategy works too — it is \"on request only\": the daily automation never posts for it, and an AI caption is written from the Page's name and category plus your `topic` (no AI image). This does NOT publish — call /posts/{postId}/publish next.","security":[{"bearerAuth":[]}],"parameters":[{"name":"pageId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object"},"example":{"topic":"this week's fresh catch"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":{"id":"d41c...","caption":"Fresh catch just arrived...","status":"draft","quality_score":0.82}}}}},"400":{"description":"invalid_body — neither `topic` nor `caption` was sent, or a field fails validation","content":{"application/json":{"example":{"error":{"code":"invalid_body","message":"neither `topic` nor `caption` was sent, or a field fails validation"}}}}},"401":{"description":"unauthorized — the key is missing, malformed, or revoked","content":{"application/json":{"example":{"error":{"code":"unauthorized","message":"the key is missing, malformed, or revoked"}}}}},"404":{"description":"not_found — no Page with that id on this account","content":{"application/json":{"example":{"error":{"code":"not_found","message":"no Page with that id on this account"}}}}}}}},"/pages/{pageId}/media":{"post":{"operationId":"addPageMedia","summary":"Hold an image for the scheduler to post later","description":"Adds an image to this Page's held-media queue instead of posting it immediately. The daily scheduler uses the oldest held image before generating anything fresh — this is how another app hands dPoster a backlog of photos to post over time. `image_url` must already be publicly hosted. Optional `caption` skips AI captioning when this item is used; leave it out and our AI writes one. This does NOT create a post yet — for that, see /pages/{pageId}/drafts.","security":[{"bearerAuth":[]}],"parameters":[{"name":"pageId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object"},"example":{"image_url":"https://example.com/product-photo.jpg","caption":"Fresh batch just arrived!"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":{"id":"m91a...","image_url":"https://example.com/product-photo.jpg","caption":"Fresh batch just arrived!","status":"available"}}}}},"400":{"description":"invalid_body — `image_url` is missing or not a valid URL","content":{"application/json":{"example":{"error":{"code":"invalid_body","message":"`image_url` is missing or not a valid URL"}}}}},"401":{"description":"unauthorized — the key is missing, malformed, or revoked","content":{"application/json":{"example":{"error":{"code":"unauthorized","message":"the key is missing, malformed, or revoked"}}}}},"404":{"description":"not_found — no Page with that id on this account","content":{"application/json":{"example":{"error":{"code":"not_found","message":"no Page with that id on this account"}}}}}}},"get":{"operationId":"listPageMedia","summary":"List a Page's held-media queue","description":"Every image held for this Page, most recent first, with its status: `available` (waiting), `queued` (claimed by the scheduler this instant), `used` (already placed into a post), or `archived`.","security":[{"bearerAuth":[]}],"parameters":[{"name":"pageId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":[{"id":"m91a...","image_url":"https://example.com/product-photo.jpg","caption":null,"status":"available"}]}}}},"401":{"description":"unauthorized — the key is missing, malformed, or revoked","content":{"application/json":{"example":{"error":{"code":"unauthorized","message":"the key is missing, malformed, or revoked"}}}}},"404":{"description":"not_found — no Page with that id on this account","content":{"application/json":{"example":{"error":{"code":"not_found","message":"no Page with that id on this account"}}}}}}}},"/posts":{"get":{"operationId":"listPosts","summary":"List recent posts","description":"Optional query params: `page_id` to filter to one Page, `limit` (1-100, default 20).","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":[{"id":"d41c...","page_id":"b6f2...","status":"published","facebook_post_id":"12218...","published_at":"2026-09-13T13:00:00.000Z"}]}}}},"401":{"description":"unauthorized — the key is missing, malformed, or revoked","content":{"application/json":{"example":{"error":{"code":"unauthorized","message":"the key is missing, malformed, or revoked"}}}}}}}},"/posts/{postId}/publish":{"post":{"operationId":"publishPost","summary":"Publish a draft","description":"Optional body: `{ \"target\": \"facebook\" | \"instagram\" | \"both\" }`, default `facebook`. A post that is already publishing, published, or failed cannot be published again from here. If two requests for the same post arrive together, only one publishes; the other gets 409.","security":[{"bearerAuth":[]}],"parameters":[{"name":"postId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object"},"example":{"target":"facebook"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":{"success":true,"facebook_post_id":"12218...","instagram_post_id":null}}}}},"400":{"description":"invalid_body — `target` is not one of the allowed values","content":{"application/json":{"example":{"error":{"code":"invalid_body","message":"`target` is not one of the allowed values"}}}}},"401":{"description":"unauthorized — the key is missing, malformed, or revoked","content":{"application/json":{"example":{"error":{"code":"unauthorized","message":"the key is missing, malformed, or revoked"}}}}},"404":{"description":"not_found — no post with that id on this account","content":{"application/json":{"example":{"error":{"code":"not_found","message":"no post with that id on this account"}}}}},"409":{"description":"invalid_state — the post is not draft/approved, or another request is already publishing it","content":{"application/json":{"example":{"error":{"code":"invalid_state","message":"the post is not draft/approved, or another request is already publishing it"}}}}},"502":{"description":"(none — check `errors` in the response body) — Facebook or Instagram rejected the publish","content":{"application/json":{"example":{"error":{"code":"(none — check `errors` in the response body)","message":"Facebook or Instagram rejected the publish"}}}}}}}}}}