{ "openapi": "3.1.0", "info": { "title": "SteadyFeed API", "version": "1.0.0", "description": "Run a brand's Instagram from your agent or app. Tell SteadyFeed what to post about with a Drop; it plans, writes, designs and checks the posts. Posts wait for the brand's OK unless the key may post on its own (Settings → API and MCP). Each key gets an hourly allowance by plan.", "contact": { "email": "hello@steadyfeed.app", "url": "https://steadyfeed.app/agents" } }, "servers": [ { "url": "https://steadyfeed.app/api/v1" } ], "security": [ { "key": [] } ], "paths": { "/brand": { "get": { "operationId": "brandInfo", "summary": "The brand this key belongs to", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Brand" } } } }, "400": { "description": "Problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/posts": { "get": { "operationId": "listPosts", "summary": "Posts on the plan, soonest first", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string" }, "description": "idea, draft, review, ready, scheduled or posted. review is what waits for the team." }, { "name": "from", "in": "query", "schema": { "type": "string" }, "description": "First date, YYYY-MM-DD" }, { "name": "to", "in": "query", "schema": { "type": "string" }, "description": "Last date, YYYY-MM-DD" }, { "name": "limit", "in": "query", "schema": { "type": "integer" }, "description": "1 to 200, default 50" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "posts": { "type": "array", "items": { "$ref": "#/components/schemas/Post" } } } } } } }, "400": { "description": "Problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/posts/{id}": { "get": { "operationId": "getPost", "summary": "One post in full", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The post's id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Post" } } } }, "400": { "description": "Problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "updatePost", "summary": "Move a post or change its caption", "description": "Send only what changes. A new caption on an approved post may send it back for an OK.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The post's id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "date": { "type": [ "string", "null" ], "format": "date" }, "hour": { "type": "integer", "minimum": 0, "maximum": 23 }, "caption": { "type": "string", "maxLength": 2200 } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Post" } } } }, "400": { "description": "Problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/posts/{id}/approve": { "post": { "operationId": "approvePost", "summary": "Approve the exact version the person reviewed", "description": "Only approve what the person asked you to. Send the approval_version from the post you showed them; if it changed, show the new one and ask again.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The post's id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expected_version": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "expected_version" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Post" } } } }, "409": { "description": "Problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/posts/{id}/request-changes": { "post": { "operationId": "requestChanges", "summary": "Send a post back with a note", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The post's id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "note": { "type": "string", "maxLength": 2000 } }, "required": [ "note" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Post" } } } }, "400": { "description": "Problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/drops": { "post": { "operationId": "addDrop", "summary": "Tell SteadyFeed what to post about", "description": "An idea, news, an offer, a link and pictures. Mention a day in text if it matters. Writing takes a minute or two; follow it with getDrop.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string", "description": "What to post about, in plain words." }, "link": { "type": "string", "format": "uri", "description": "A web page to read." }, "image_urls": { "type": "array", "maxItems": 8, "items": { "type": "string", "format": "uri" }, "description": "Public https picture addresses." }, "images": { "type": "array", "maxItems": 8, "items": { "type": "string", "contentEncoding": "base64" }, "description": "Pictures as base64, about 3 MB in all per call." }, "date": { "type": "string", "format": "date", "description": "The day the first post goes out." }, "hour": { "type": "integer", "minimum": 0, "maximum": 23, "description": "The hour that day, brand time." }, "keep_words": { "type": "boolean", "description": "Use text as the caption, as written; makes one post." } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Drop" } } } }, "400": { "description": "Problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/drops/{id}": { "get": { "operationId": "getDrop", "summary": "How a Drop is doing", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The Drop's id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Drop" } } } }, "400": { "description": "Problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/contacts": { "get": { "operationId": "listContacts", "summary": "Contacts changed since a time", "parameters": [ { "name": "updated_since", "in": "query", "schema": { "type": "string" }, "description": "ISO date and time" }, { "name": "limit", "in": "query", "schema": { "type": "integer" }, "description": "1 to 500" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "addContact", "summary": "Add someone to Contacts", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" }, "instagram": { "type": "string", "description": "Handle without the @" }, "note": { "type": "string" } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/contacts/{id}": { "patch": { "operationId": "updateContact", "summary": "Change a contact's stage, tags, notes or follow-up", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The contact's id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "stage": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "notes": { "type": "string" }, "follow_up_on": { "type": [ "string", "null" ], "description": "YYYY-MM-DD, or null to clear" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/drops/{id}/answer": { "post": { "operationId": "answerDrop", "summary": "Answer the question a Drop asked", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The Drop's id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "answer": { "type": "string", "maxLength": 2000 } }, "required": [ "answer" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Drop" } } } }, "400": { "description": "Problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/posts/{id}/hold": { "post": { "operationId": "holdPost", "summary": "Stop an approved post from going out", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The post's id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "note": { "type": "string", "maxLength": 2000 } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Post" } } } }, "400": { "description": "Problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/memory": { "post": { "operationId": "remember", "summary": "Tell Brand memory something lasting", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string", "maxLength": 300 }, "kind": { "type": "string", "enum": [ "about", "audience", "offer", "fact", "belief", "never", "voice" ] } }, "required": [ "text" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "remembered": { "type": "boolean" }, "kind": { "type": "string" }, "text": { "type": "string" }, "note": { "type": [ "string", "null" ] } } } } } }, "400": { "description": "Problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/results": { "get": { "operationId": "results", "summary": "How the last days went", "parameters": [ { "name": "days", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 90 }, "description": "Default 7" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "days": { "type": "integer" }, "posts": { "type": "integer" }, "reach": { "type": "integer" }, "likes": { "type": "integer" }, "comments": { "type": "integer" }, "saves": { "type": "integer" }, "shares": { "type": "integer" }, "best": { "type": [ "object", "null" ] }, "new_contacts": { "type": "integer" }, "new_contacts_from_posts": { "type": "integer" }, "note": { "type": "string" } } } } } }, "401": { "description": "Problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Problem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "key": { "type": "http", "scheme": "bearer", "description": "A key from Settings → API and MCP (sf_live_…)." } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "string" } } }, "Brand": { "type": "object", "properties": { "name": { "type": "string" }, "instagram": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] }, "pillars": { "type": "array", "items": {} }, "time_zone": { "type": "string" }, "plan": { "type": "string" } } }, "Post": { "type": "object", "properties": { "id": { "type": "string" }, "approval_version": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string" }, "date": { "type": [ "string", "null" ] }, "hour": { "type": [ "integer", "null" ] }, "format": { "type": "string" }, "caption": { "type": "string" }, "hashtags": { "type": "string" }, "first_comment": { "type": [ "string", "null" ] }, "slides": { "type": "array", "items": { "type": "object", "properties": { "heading": { "type": "string" }, "text": { "type": "string" } } } }, "approved_by": { "type": [ "string", "null" ] }, "approved_at": { "type": [ "string", "null" ] }, "instagram": { "type": [ "object", "null" ] }, "results": {}, "url": { "type": "string" }, "updated_at": { "type": [ "string", "null" ] } } }, "Drop": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "new", "working", "done", "question", "failed" ] }, "text": { "type": "string" }, "link": { "type": [ "string", "null" ] }, "reply": { "type": [ "string", "null" ] }, "question": { "type": [ "string", "null" ], "description": "Something to answer in the app." }, "error": { "type": [ "string", "null" ] }, "auto_publish": { "type": "boolean", "description": "Posts that pass the quality check go out on their own." }, "posts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "date": { "type": [ "string", "null" ] }, "passed_check": { "type": "boolean" }, "score": { "type": [ "number", "null" ] }, "held_because": { "type": "array", "items": { "type": "string" } } } } }, "created_at": { "type": "string" } } } } } }