# SosoAPI-publiserings-API: autentisering, forespørsler og resultater Kanonisk URL: https://sosoapi.ai/nb/docs/publishing-api-reference Bygg en publiseringsintegrasjon på serveren rundt ett planlagt innlegg per mål. Denne referansen dekker publiserings-API-kontrakten gjennomgått 20. oktober 2026. Eksemplene inneholder plassholdere og kjøres ikke på denne siden. ## 1. Autentiser fra serveren din Opprett en API-nøkkel i SosoAPI-appen → Innstillinger → Agenter og API-tilgang. Lagre den som SOSOAPI_API_KEY i servermiljøet. Forespørsler bruker Authorization: Bearer og Content-Type: application/json. Bygg aldri nøkkelen inn i et nettsted, en mobilapp-pakke, en URL eller et offentlig repositorium. Alle endepunktene nedenfor bruker POST med JSON-innhold. Nøkler og delegerte agenttillatelser begrenses av funksjoner, tillatte arbeidsområder og eierens gjeldende medlemskap. Lesing trenger agent:operate og minst viewer-tilgang; publiseringsendringer trenger agent:publish og minst editor-tilgang. En tillatelse kan ikke utvide eierens rettigheter. Bruk appens gjeldende arbeidsområde og tilkoblede kontoer, eller kall /identity-api/workspace/list og /identity-api/user/social-accounts/list for å finne ID-er du er autorisert til å bruke. Ikke gjett en kundes arbeidsområde- eller konto-ID. ``` // Node.js 20+; run only on your server. const apiKey = process.env.SOSOAPI_API_KEY; if (!apiKey) throw new Error("Set SOSOAPI_API_KEY on your server"); const apiBase = "https://gqeshlawtcexsapabaui.supabase.co/functions/v1"; async function sosoPost(path, body) { const response = await fetch(apiBase + path, { method: "POST", headers: { Authorization: "Bearer " + apiKey, "Content-Type": "application/json" }, body: JSON.stringify(body) }); const result = await response.json(); if (!response.ok) { const requestId = result.request_id ?? response.headers.get("x-request-id"); // Handler errors use code/message; schema-validation 400s instead use // success:false and error:{name:"ZodError",message:...}. // Preserve status, available code and requestId in server diagnostics. // Never log the key or an Authorization header. throw new Error("SosoAPI " + response.status + " (" + (requestId ?? "no request id") + ")"); } return result; } ``` ## 2. Oversikt over publiseringsendepunkter Disse banene er relative til API-basen som serverhjelperen bruker. Hent innleggsdetaljene for å få gjeldende versjon, tilgjengelige handlinger og publiseringsresultat. Endepunkter for planlagte innlegg; hver forespørsel er POST | Bane | Forespørsel | Svar og grense | | --- | --- | --- | | /studio-api/scheduled-posts/list | workspace_id; valgfri project_id, status, tidspar, limit, cursor. | posts, next_cursor, returned_count. Lesing avgrenset til arbeidsområdet. | | /studio-api/scheduled-posts/get | id. | post, delivery, actions, attempts, outcomes. Les gjeldende versjon her. | | /studio-api/scheduled-posts/eligibility | workspace_id, targets; valgfri include_quota. | mål og valgfri kvote. Skrivebeskyttet forhåndskontroll, ikke en reservasjon. | | /studio-api/scheduled-posts/create | workspace_id, nøyaktig konto, provider_payload, innhold, scheduled_at, idempotency_key. | post og deduped. 201 for en ny publiseringsplan; 200 for en samsvarende gjentakelse. | | /studio-api/scheduled-posts/bulk-create | workspace_id og 1–50 targets, hver med sin egen idempotency_key. | batch_id, successes, failures. 201 når minst ett lykkes; 422 når ingen lykkes. Undersøk begge arrayene. | | /studio-api/scheduled-posts/update | id, expected_version, patch; valgfri samsvarende provider_payload. | post. En utdatert versjon avvises; målet kan ikke endres. | | /studio-api/scheduled-posts/publish-now | id og expected_version. | post. Ber om umiddelbar kjøring; beviser ikke publisering. | | /studio-api/scheduled-posts/retry | id, expected_version; valgfri fremtidig scheduled_at. | post. Bare mislykkede, med dokumentasjonsstyrt gjenoppretting; aldri blind ny sending. | | /studio-api/scheduled-posts/cancel | id og expected_version. | post. Avbryter upublisert arbeid; ekstern avbryting kan fortsatt vente. | | /studio-api/scheduled-posts/delete | id og expected_version. | post. Maskininnkallere kan ikke slette leverandørinnhold som allerede er publisert. | | /studio-api/scheduled-posts/withdraw-delete | id og expected_version. | post. Trekker tilbake en stanset Instagram Login-sletteforespørsel som bare gjelder verifisering; beholder leverandørinnhold. | ## 3. Vis og paginer uten å miste omfanget limit er 50 som standard og godtar 1–200. Valgfri status er en av scheduled, publishing, published, failed, expired, needs_reschedule, cancelled eller deleted. scheduled_from og scheduled_to må oppgis sammen som ISO-8601-tidspunkter med tidssoneforskyvning; slutt må være etter start. next_cursor er enten null eller et objekt med scheduled_at og id. Send hele objektet tilbake som cursor sammen med samme arbeidsområde og filtre. Dette endepunktet godtar ikke filtrene page, offset, platform eller social_account_id. ``` await sosoPost("/studio-api/scheduled-posts/list", { "workspace_id": "", "limit": 50 }); ``` ``` const first = await sosoPost("/studio-api/scheduled-posts/list", { workspace_id: "", limit: 50 }); if (first.next_cursor) { const next = await sosoPost("/studio-api/scheduled-posts/list", { workspace_id: "", limit: 50, cursor: first.next_cursor }); // Consume next.posts; continue only while next_cursor is not null. } ``` ## 4. Valider og opprett ett gjennomgått innlegg Erstatt alle plassholdere med verdier fra det autoriserte omfanget ditt og et fremtidig tidspunkt. Dette eksemplet planlegger et faktisk tekstinnlegg på Threads når det kjøres. Innhent personens bekreftelse på konto, innhold og tidspunkt før create-kallet. Angi provider_payload.platform og plattformens publish_options. Serveren kontrollerer at de samsvarer med valgt konto. Du kan inkludere project_id for å registrere hvor innlegget kom fra; prosjektet gir ikke publiseringstilgang og styrer ikke publiseringsplanen. Felter og standardverdier i opprettingsforespørselen | Felt | Kontrakt | | --- | --- | | workspace_id / social_account_id | Påkrevde UUID-er for autorisert arbeidsområde og nøyaktig mål. | | provider_payload | Påkrevd platform-diskriminator og plattformspesifikke publish_options. | | scheduled_at / display_timezone | Påkrevd ISO-8601-tidspunkt med forskyvning; gyldig IANA-visningstidssone, standard UTC. | | idempotency_key | Påkrevd streng uten innledende eller avsluttende mellomrom, 8–160 tegn, stabil for denne ene hensikten. | | caption / hashtags | Caption kan være null og ha høyst 5,000 tegn; standard er null. Hashtags har [] som standard; høyst 100 strenger med 100 tegn. Leverandørgrensene kan være strengere. | | media | Standard []; høyst 20 registrerte mediereferanser. Hver har kind image/video og en kanonisk url; inkluder klar asset_id. Plattformregler kan være strengere. | | link_url | Valgfri URL eller null. Mål og innleggstype må støtte den. | | local_scheduled_at / schedule_dst_disambiguation | Valgfritt par: lokal tid uten forskyvning og exact/earlier/later. Oppgi begge eller ingen; de må samsvare med ønsket tidspunkt og tidssone. | | expires_at / automatic_retry_enabled | Valgfritt utløp etter scheduled_at; null betyr ingen utløpsdato. Automatisk nytt forsøk er true som standard og er fortsatt underlagt leverandørsikkerhet. | | project_id / source_ref | Valgfri Project-UUID som kan være null, og objekt for innkallerens opphav. Ingen av dem endrer autoritet. | ``` await sosoPost("/studio-api/scheduled-posts/eligibility", { "workspace_id": "", "include_quota": true, "targets": [ { "social_account_id": "", "media": [], "provider_payload": { "platform": "threads", "publish_options": { "post_type": "TEXT" } }, "draft": { "caption": "A reviewed update from our team.", "hashtags": [], "scheduled_at": "", "display_timezone": "Asia/Hong_Kong" } } ] }); ``` ``` await sosoPost("/studio-api/scheduled-posts/create", { "workspace_id": "", "social_account_id": "", "caption": "A reviewed update from our team.", "hashtags": [], "media": [], "provider_payload": { "platform": "threads", "publish_options": { "post_type": "TEXT" } }, "scheduled_at": "", "display_timezone": "Asia/Hong_Kong", "idempotency_key": "" }); ``` ## 5. Les resultatet og avbryt trygt Create returnerer { post, deduped }. List returnerer { posts, next_cursor, returned_count }. Get returnerer { post, delivery, actions, attempts, outcomes }. Et innlegg inneholder id, status, version, destination, schedule og tilgjengelig leverandøridentitet/permelenke; delivery og actions forklarer gjeldende fremdrift og tillatte neste trinn. Et innlegg med status scheduled eller publishing venter fortsatt. Et endelig publiseringsresultat med status published bekrefter publisering og inkluderer leverandørdokumentasjonen som er tilgjengelig for innlegget; en permalenke kan mangle. Les eksisterende innlegg før du rapporterer resultat hvis klienten kobles fra eller svaret forsinkes. Hent innleggsdetaljer og oppgi gjeldende numerisk version før avbryting. Resultatet kan være cancellation_pending mens SosoAPI avbryter en publiseringsplan hos leverandøren. Avbryting av en publiseringsplan sletter ikke et allerede publisert innlegg. ``` await sosoPost("/studio-api/scheduled-posts/get", { "id": "" }); ``` ``` const detail = await sosoPost("/studio-api/scheduled-posts/get", { id: "" }); // Run only after the person confirms cancelling this unpublished post. await sosoPost("/studio-api/scheduled-posts/cancel", { id: detail.post.id, expected_version: detail.post.version }); ``` ## 6. Idempotens, konflikter og usikre skriveoperasjoner Bruk samme idempotency_key når du gjentar samme opprettingsforespørsel. En samsvarende gjentakelse returnerer det eksisterende innlegget med deduped=true. Hvis innholdet endres mens nøkkelen gjenbrukes, oppstår en konflikt. Dette hindrer dupliserte opprettinger i SosoAPI; det garanterer ikke levering nøyaktig én gang hos leverandøren. Oppgi expected_version fra siste detaljsvar ved oppdateringer og handlinger. Ved konflikt, hent innlegget på nytt og gjennomgå endringen mot ny versjon. Et tapt svar er grunn til å kontrollere eksisterende tilstand, ikke opprette et nytt innlegg med ny nøkkel. Vernet mot duplisert innhold kan avvise en separat forespørsel med samme normaliserte offentlige innhold, konto og nærliggende publiseringstidspunkt. Undersøk referansen til det eksisterende innlegget hvis du er autorisert til å lese det, og spør brukeren før forespørselen endres. Masseforespørsler returnerer et resultat for hvert mål; noen kan lykkes mens andre mislykkes. ## 7. Feil, frekvensgrenser og integrasjonsgrenser Håndteringsfeil bruker en konvolutt med error, message, valgfri code, retryable, request_id, valgfri details og retry_after_seconds. 400-svar fra skjemavalidering returnerer en annen struktur: { success: false, error: { name: "ZodError", message: "…" } }. Valideringsmeldingen inneholder for øyeblikket de serialiserte feltfeilene, inkludert banene deres; ikke anta at feltene fra håndteringskonvolutten finnes. Behold HTTP-status, feilkode og korrelasjons-ID fra result.request_id ?? response.headers.get("x-request-id") ved feilsøking. Bruk valideringsfeltbaner til å rette forespørselen. Rett legitimasjon eller tillatelse før nye forsøk ved autentiserings- eller tillatelsesfeil. Gjeldende studio-api-grense er 240 forespørsler per minutt per menneskelig bruker og 480 per minutt i brukerens separate maskinlegitimasjonskvote. Dette er forespørselstak, ikke publiseringskapasitet eller abonnementskvoter. Andre endepunkter og sosiale leverandører har separate grenser. Følg gjeldende Retry-After-header ved 429 eller 503 som kan prøves på nytt; ikke bruk en tett løkke. Les status med avgrensede intervaller mens brukeren følger innlegget, eller bruk appens direkte statusvisning. Dette API-et lover ikke utgående webhooks, abonnent-SLA, identiske funksjoner på tvers av plattformer eller et fast publiseringstidspunkt. HTTP-svar og nyttige neste handlinger | Status | Betydning og svar | | --- | --- | | 400 | Skjemavalidering kan returnere success:false med en ZodError i error i stedet for håndteringskonvolutten. Rett feltfeilene; bruk x-request-id hvis innholdet ikke har request_id. Ugyldige eller ustøttede forespørsler på håndterernivå kan også bruke 400. | | 401 / 403 | Manglende/utløpt legitimasjon eller nektet funksjon, rolle, arbeidsområde- eller kontotilgang. Rett den nøyaktige tillatelsen eller medlemskapet. | | 404 | Ressursen er utilgjengelig innenfor autorisert omfang. Verifiser identiteten. | | 409 | Konflikt i tilstand/versjon, idempotens, duplisert innhold eller kvalifikasjon. Les på nytt; ikke send blindt igjen. | | 422 ved masseoppretting | Ingen mål lyktes. Undersøk failures; delvis suksess bruker 201 i stedet. | | 429 | Forespørselsbegrensning. Følg Retry-After og behold samme hensiktsidentitet. | | 503 / andre 5xx | Midlertidig tjenestefeil eller intern feil. Behold request_id; undersøk eksisterende tilstand før du prøver en usikker endring på nytt. | - [Plattformens funksjonsmatrise](https://sosoapi.ai/nb/docs/publishing-capabilities) - [Sett opp din egen AI-agent](https://sosoapi.ai/nb/docs/quickstart)