{
  "openapi": "3.1.0",
  "info": {
    "title": "Socora API",
    "version": "0.3.0",
    "description": "A normalized social backend for SaaS products. Provider identifiers and upstream errors are never part of the public contract."
  },
  "servers": [{ "url": "https://api.socora.dev" }],
  "security": [{ "bearerAuth": [] }],
  "tags": [
    { "name": "Profiles" }, { "name": "Connect" }, { "name": "Social accounts" },
    { "name": "Posts" }, { "name": "Analytics" },
    { "name": "Webhooks" }, { "name": "Usage" }
  ],
  "paths": {
    "/v1/profiles": {
      "get": { "tags": ["Profiles"], "summary": "List Customer Profiles", "parameters": [{ "name": "external_id", "in": "query", "schema": { "type": "string" } }, { "name": "type", "in": "query", "schema": { "type": "string", "enum": ["business", "creator", "person", "brand", "other"] } }, { "name": "search", "in": "query", "schema": { "type": "string" } }, { "name": "include_archived", "in": "query", "schema": { "type": "boolean", "default": false } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }], "responses": { "200": { "description": "Customer Profiles", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileList" } } } } } },
      "post": { "tags": ["Profiles"], "summary": "Create a Customer Profile", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileCreate" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileEnvelope" } } } }, "409": { "$ref": "#/components/responses/Error" } } }
    },
    "/v1/profiles/{id}": {
      "parameters": [{ "$ref": "#/components/parameters/Id" }],
      "get": { "tags": ["Profiles"], "summary": "Retrieve a Customer Profile", "responses": { "200": { "description": "Profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileEnvelope" } } } }, "404": { "$ref": "#/components/responses/Error" } } },
      "patch": { "tags": ["Profiles"], "summary": "Update a Customer Profile", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfilePatch" } } } }, "responses": { "200": { "description": "Updated profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileEnvelope" } } } } } },
      "delete": { "tags": ["Profiles"], "summary": "Delete a Customer Profile", "responses": { "204": { "description": "Deleted" } } }
    },
    "/v1/profiles/{id}/capabilities": {
      "get": { "tags": ["Profiles"], "summary": "Read profile capabilities", "parameters": [{ "$ref": "#/components/parameters/Id" }], "responses": { "200": { "description": "Normalized profile capabilities" } } }
    },
    "/v1/profiles/{id}/activity": {
      "get": { "tags": ["Profiles"], "summary": "Read profile activity", "parameters": [{ "$ref": "#/components/parameters/Id" }], "responses": { "200": { "description": "Profile activity summary" } } }
    },
    "/v1/connect-sessions": {
      "post": { "tags": ["Connect"], "summary": "Create a hosted Connect session", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectSessionCreate" } } } }, "responses": { "201": { "description": "Short-lived hosted Connect URL" }, "422": { "$ref": "#/components/responses/Error" } } }
    },
    "/v1/social-accounts": {
      "get": { "tags": ["Social accounts"], "summary": "List normalized social accounts", "parameters": [{ "name": "profile_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }], "responses": { "200": { "description": "Account list with next_cursor" } } }
    },
    "/v1/social-accounts/{id}/feed": {
      "get": { "tags": ["Analytics"], "summary": "List normalized account feed items", "parameters": [{ "$ref": "#/components/parameters/Id" }], "responses": { "200": { "description": "Feed items" } } }
    },
    "/v1/social-accounts/{id}/analytics": {
      "get": { "tags": ["Analytics"], "summary": "Retrieve metric snapshots", "parameters": [{ "$ref": "#/components/parameters/Id" }], "responses": { "200": { "description": "Metrics preserve unavailable and not-supported values" } } }
    },
    "/v1/social-accounts/{id}/disconnect": {
      "post": { "tags": ["Social accounts"], "summary": "Disconnect a social account", "parameters": [{ "$ref": "#/components/parameters/Id" }], "responses": { "200": { "description": "Disconnected account" }, "404": { "$ref": "#/components/responses/Error" } } }
    },
    "/v1/social-accounts/{id}/reconnect-session": {
      "post": { "tags": ["Connect"], "summary": "Create a hosted reconnect session", "parameters": [{ "$ref": "#/components/parameters/Id" }], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "return_url": { "type": "string", "format": "uri" } } } } } }, "responses": { "201": { "description": "Short-lived hosted reconnect URL" } } }
    },
    "/v1/posts": {
      "get": { "tags": ["Posts"], "summary": "List posts", "parameters": [{ "name": "profile_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }], "responses": { "200": { "description": "Posts with next_cursor" } } },
      "post": { "tags": ["Posts"], "summary": "Queue a multi-platform post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostCreate" } } } }, "responses": { "202": { "description": "Queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Post" } } } }, "403": { "$ref": "#/components/responses/Error" } } }
    },
    "/v1/posts/{id}/results": {
      "get": { "tags": ["Posts"], "summary": "List per-platform delivery results", "parameters": [{ "$ref": "#/components/parameters/Id" }], "responses": { "200": { "description": "One result per target" } } }
    },
    "/v1/posts/{id}": {
      "parameters": [{ "$ref": "#/components/parameters/Id" }],
      "get": { "tags": ["Posts"], "summary": "Retrieve a post", "responses": { "200": { "description": "Post" }, "404": { "$ref": "#/components/responses/Error" } } },
      "patch": { "tags": ["Posts"], "summary": "Update a queued or scheduled post", "responses": { "200": { "description": "Updated post" }, "409": { "$ref": "#/components/responses/Error" } } },
      "delete": { "tags": ["Posts"], "summary": "Cancel a queued or scheduled post", "responses": { "204": { "description": "Cancelled" } } }
    },
    "/v1/webhooks": {
      "get": { "tags": ["Webhooks"], "summary": "List webhook endpoints", "responses": { "200": { "description": "Endpoints" } } },
      "post": { "tags": ["Webhooks"], "summary": "Create a signed webhook endpoint", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookCreate" } } } }, "responses": { "201": { "description": "Secret shown once" }, "409": { "$ref": "#/components/responses/Error" } } }
    },
    "/v1/webhooks/{id}": {
      "parameters": [{ "$ref": "#/components/parameters/Id" }],
      "get": { "tags": ["Webhooks"], "summary": "Retrieve a webhook endpoint", "responses": { "200": { "description": "Endpoint" }, "404": { "$ref": "#/components/responses/Error" } } },
      "patch": { "tags": ["Webhooks"], "summary": "Update a webhook endpoint", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPatch" } } } }, "responses": { "200": { "description": "Updated endpoint" } } },
      "delete": { "tags": ["Webhooks"], "summary": "Delete a webhook endpoint", "responses": { "204": { "description": "Deleted" } } }
    },
    "/v1/webhooks/{id}/deliveries": {
      "get": { "tags": ["Webhooks"], "summary": "List webhook delivery attempts", "parameters": [{ "$ref": "#/components/parameters/Id" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }], "responses": { "200": { "description": "Delivery history with next_cursor" } } }
    },
    "/v1/webhooks/{id}/test": {
      "post": { "tags": ["Webhooks"], "summary": "Send a test webhook", "parameters": [{ "$ref": "#/components/parameters/Id" }], "responses": { "202": { "description": "Test queued" } } }
    },
    "/v1/webhooks/{id}/rotate-secret": {
      "post": { "tags": ["Webhooks"], "summary": "Rotate a webhook secret", "parameters": [{ "$ref": "#/components/parameters/Id" }], "responses": { "200": { "description": "New secret shown once" } } }
    },
    "/v1/webhooks/{id}/replay": {
      "post": { "tags": ["Webhooks"], "summary": "Replay a webhook delivery", "parameters": [{ "$ref": "#/components/parameters/Id" }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["delivery_id"], "properties": { "delivery_id": { "type": "string", "format": "uuid" } } } } } }, "responses": { "202": { "description": "Replay queued" } } }
    },
    "/v1/usage": {
      "get": { "tags": ["Usage"], "summary": "Read live usage from Socora's ledger", "parameters": [{ "name": "profile_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "external_id", "in": "query", "schema": { "type": "string" } }, { "name": "event_type", "in": "query", "schema": { "type": "string" } }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }], "responses": { "200": { "description": "Current-period usage" } } }
    },
    "/v1/billing/estimate": {
      "get": { "tags": ["Usage"], "summary": "Estimate the current invoice", "responses": { "200": { "description": "Approximate bill" } } }
    }
  },
  "components": {
    "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "live_…" } },
    "parameters": { "Id": { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } },
    "responses": { "Error": { "description": "Normalized error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } },
    "schemas": {
      "ProfileCreate": { "type": "object", "required": ["external_id", "name"], "properties": { "external_id": { "type": "string", "maxLength": 255 }, "name": { "type": "string", "maxLength": 200 }, "type": { "enum": ["business", "creator", "person", "brand", "other"], "default": "other" }, "metadata": { "type": "object", "additionalProperties": true } } },
      "ProfilePatch": { "type": "object", "minProperties": 1, "properties": { "external_id": { "type": "string", "maxLength": 255 }, "name": { "type": "string", "maxLength": 200 }, "type": { "enum": ["business", "creator", "person", "brand", "other"] }, "metadata": { "type": "object", "additionalProperties": true } } },
      "Profile": { "type": "object", "required": ["id", "project_id", "external_id", "name", "type", "metadata", "archived_at", "created_at", "updated_at"], "properties": { "id": { "type": "string", "format": "uuid" }, "project_id": { "type": "string", "format": "uuid" }, "external_id": { "type": "string" }, "name": { "type": "string" }, "type": { "enum": ["business", "creator", "person", "brand", "other"] }, "metadata": { "type": "object", "additionalProperties": true }, "archived_at": { "type": ["string", "null"], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } },
      "ProfileEnvelope": { "type": "object", "required": ["data"], "properties": { "data": { "$ref": "#/components/schemas/Profile" } } },
      "ProfileList": { "type": "object", "required": ["data", "next_cursor"], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Profile" } }, "next_cursor": { "type": ["string", "null"] } } },
      "ConnectSessionCreate": { "type": "object", "required": ["profile_id", "platforms"], "properties": { "profile_id": { "type": "string", "format": "uuid" }, "platforms": { "type": "array", "minItems": 1, "items": { "enum": ["instagram", "facebook", "tiktok", "linkedin", "youtube", "threads", "pinterest", "bluesky"] } }, "features": { "type": "array", "items": { "enum": ["publishing", "analytics"] } }, "return_url": { "type": "string", "format": "uri" } } },
      "PostCreate": { "type": "object", "required": ["profile_id", "social_account_ids", "caption"], "properties": { "profile_id": { "type": "string" }, "social_account_ids": { "type": "array", "minItems": 1, "items": { "type": "string" } }, "caption": { "type": "string" }, "media": { "type": "array", "items": { "type": "object", "required": ["url"], "properties": { "url": { "type": "string", "format": "uri" } } } }, "scheduled_at": { "type": ["string", "null"], "format": "date-time" } } },
      "Post": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "enum": ["queued", "scheduled", "processing", "partially_succeeded", "succeeded", "failed", "cancelled"] } } },
      "WebhookCreate": { "type": "object", "required": ["url"], "properties": { "url": { "type": "string", "format": "uri", "description": "Public HTTPS endpoint." }, "events": { "type": "array", "items": { "type": "string" } } } },
      "WebhookPatch": { "type": "object", "minProperties": 1, "properties": { "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string" } }, "enabled": { "type": "boolean" } } },
      "Webhook": { "type": "object", "required": ["id", "project_id", "url", "events", "enabled", "secret_prefix", "created_at", "updated_at"], "properties": { "id": { "type": "string", "format": "uuid" }, "project_id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string" } }, "enabled": { "type": "boolean" }, "secret_prefix": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } },
      "WebhookList": { "type": "object", "required": ["data"], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } } } },
      "WebhookCreateResponse": { "type": "object", "required": ["data"], "properties": { "data": { "allOf": [{ "$ref": "#/components/schemas/Webhook" }, { "type": "object", "required": ["secret"], "properties": { "secret": { "type": "string", "description": "Returned only on create and rotation." } } }] } } },
      "Error": { "type": "object", "required": ["error"], "properties": { "error": { "type": "object", "required": ["code", "message", "request_id", "details"], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } } } } }
    }
  }
}