Spaces:
Running
Running
Download openapi.json from mertkayacs/postkitty-api: direct link, hf CLI and curl.
- Browser
- Download file 50.8 kB
-
https://huggingface.co/spaces/mertkayacs/postkitty-api/resolve/main/openapi.json
- Command line
-
hf download hf://spaces/mertkayacs/postkitty-api/openapi.json
-
curl -L -o openapi.json https://huggingface.co/spaces/mertkayacs/postkitty-api/resolve/main/openapi.json
50.8 kB
{
"openapi": "3.1.0",
"info": {
"title": "postkitty API",
"summary": "One post in, a checked file for every social platform out.",
"description": "Send text, one photo or one landscape video and get back files sized, framed and checked for Instagram, TikTok, YouTube Shorts, X, LinkedIn, Threads, Bluesky and Facebook. Uploads only: the service never fetches a URL, never posts anywhere, and deletes each job 60 minutes after it finishes. Every error has the same shape: `{\"error\": {\"code\", \"message\", \"hint\"}}`. Guide: https://postkitty.mertkayacs.com/docs/",
"license": {
"name": "MIT"
},
"version": "1.0.0"
},
"paths": {
"/v1/health": {
"get": {
"tags": [
"service"
],
"summary": "Is the service up",
"operationId": "health_v1_health_get",
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Health"
}
}
}
}
}
}
},
"/v1/limits": {
"get": {
"tags": [
"service"
],
"summary": "Upload, queue and rate limits",
"operationId": "limits_view_v1_limits_get",
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/LimitsView"
}
}
}
}
}
}
},
"/v1/platforms": {
"get": {
"tags": [
"service"
],
"summary": "Every platform, its targets, sizes and limits",
"operationId": "platforms_v1_platforms_get",
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PlatformList"
}
}
}
}
}
}
},
"/v1/text": {
"post": {
"tags": [
"text"
],
"summary": "Count a text with each platform's own rule",
"operationId": "count_text_v1_text_post",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TextRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TextResult"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorBody"
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorBody"
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorBody"
}
}
}
}
}
}
},
"/v1/check": {
"post": {
"tags": [
"check"
],
"summary": "Check a file you already have against one target",
"operationId": "check_file_v1_check_post",
"requestBody": {
"content": {
"multipart/form-data": {
"schema": {
"$ref": "#/components/schemas/Body_check_file_v1_check_post"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CheckResult"
}
}
}
},
"413": {
"description": "Request Entity Too Large",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorBody"
}
}
}
},
"415": {
"description": "Unsupported Media Type",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorBody"
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorBody"
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorBody"
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorBody"
}
}
}
},
"504": {
"description": "Gateway Timeout",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorBody"
}
}
}
}
}
}
},
"/v1/jobs": {
"post": {
"tags": [
"jobs"
],
"summary": "Turn one post into files for every platform",
"operationId": "create_job_v1_jobs_post",
"requestBody": {
"content": {
"multipart/form-data": {
"schema": {
"$ref": "#/components/schemas/Body_create_job_v1_jobs_post"
}
}
}
},
"responses": {
"202": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/JobAccepted"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorBody"
}
}
}
},
"413": {
"description": "Request Entity Too Large",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorBody"
}
}
}
},
"415": {
"description": "Unsupported Media Type",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorBody"
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorBody"
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorBody"
}
}
}
},
"501": {
"description": "Not Implemented",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorBody"
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorBody"
}
}
}
}
}
}
},
"/v1/jobs/{job_id}": {
"get": {
"tags": [
"jobs"
],
"summary": "Status and results of a job",
"operationId": "job_status_v1_jobs__job_id__get",
"parameters": [
{
"name": "job_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Job Id"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/JobStatus"
}
}
}
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorBody"
}
}
},
"description": "Not Found"
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
},
"delete": {
"tags": [
"jobs"
],
"summary": "Delete a job and its files now",
"operationId": "job_delete_v1_jobs__job_id__delete",
"parameters": [
{
"name": "job_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Job Id"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Deleted"
}
}
}
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorBody"
}
}
},
"description": "Not Found"
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/jobs/{job_id}/files/{path}": {
"get": {
"tags": [
"jobs"
],
"summary": "Download one result file",
"operationId": "job_file_v1_jobs__job_id__files__path__get",
"parameters": [
{
"name": "job_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Job Id"
}
},
{
"name": "path",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Path"
}
}
],
"responses": {
"200": {
"description": "Successful Response"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorBody"
}
}
},
"description": "Not Found"
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/jobs/{job_id}/download": {
"get": {
"tags": [
"jobs"
],
"summary": "Download every result as one zip",
"operationId": "job_download_v1_jobs__job_id__download_get",
"parameters": [
{
"name": "job_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Job Id"
}
}
],
"responses": {
"200": {
"description": "Successful Response"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorBody"
}
}
},
"description": "Not Found"
},
"409": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorBody"
}
}
},
"description": "Conflict"
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"Body_check_file_v1_check_post": {
"properties": {
"file": {
"type": "string",
"format": "binary",
"title": "File",
"description": "One photo or video."
},
"target": {
"type": "string",
"title": "Target",
"description": "A target id from GET /v1/platforms, for example tiktok."
}
},
"type": "object",
"required": [
"file",
"target"
],
"title": "Body_check_file_v1_check_post"
},
"Body_create_job_v1_jobs_post": {
"properties": {
"files": {
"anyOf": [
{
"items": {
"type": "string",
"format": "binary"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Files",
"description": "One photo, or one video."
},
"text": {
"type": "string",
"title": "Text",
"description": "The post text. It is counted, checked and split, never rewritten.",
"default": ""
},
"platforms": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Platforms",
"description": "Platform names or target ids, repeated or comma-separated. Leave out for every platform that fits the files."
},
"layout": {
"type": "string",
"title": "Layout",
"description": "Applies to every media target: auto, crop, split, speaker, seam or pad.",
"default": ""
},
"focus": {
"type": "string",
"title": "Focus",
"description": "Applies to every media target: auto, left, center, right, person:N or x:0.0-1.0.",
"default": ""
},
"captions": {
"anyOf": [
{
"type": "string",
"format": "binary"
},
{
"type": "null"
}
],
"title": "Captions",
"description": "An .srt or .vtt file (UTF-8, up to 1 MB) to burn into every video target. Needs a video."
}
},
"type": "object",
"title": "Body_create_job_v1_jobs_post"
},
"Check": {
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"status": {
"type": "string",
"title": "Status",
"description": "fail or advisory."
},
"hard": {
"type": "boolean",
"title": "Hard",
"description": "True when the platform rejects a file that fails this check."
},
"measured": {
"title": "Measured"
},
"expected": {
"title": "Expected"
},
"message": {
"type": "string",
"title": "Message"
},
"source_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Source Url",
"description": "Where the limit is published."
},
"checked_on": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Checked On",
"description": "The day the limit was last read from its source."
}
},
"type": "object",
"required": [
"id",
"status",
"hard",
"measured",
"expected",
"message",
"source_url",
"checked_on"
],
"title": "Check"
},
"CheckResult": {
"properties": {
"file": {
"type": "string",
"title": "File"
},
"kind": {
"type": "string",
"title": "Kind"
},
"target": {
"type": "string",
"title": "Target"
},
"pass": {
"type": "boolean",
"title": "Pass",
"description": "True when no hard check fails."
},
"checks": {
"items": {
"$ref": "#/components/schemas/Check"
},
"type": "array",
"title": "Checks",
"description": "The checks that failed or carry advice; empty when all pass."
}
},
"type": "object",
"required": [
"file",
"kind",
"target",
"pass",
"checks"
],
"title": "CheckResult"
},
"Deleted": {
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"deleted": {
"type": "boolean",
"title": "Deleted"
}
},
"type": "object",
"required": [
"id",
"deleted"
],
"title": "Deleted"
},
"ErrorBody": {
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorBody"
},
"ErrorDetail": {
"properties": {
"code": {
"type": "string",
"title": "Code",
"description": "Stable machine-readable name of the error."
},
"message": {
"type": "string",
"title": "Message",
"description": "One plain sentence that says what is wrong."
},
"hint": {
"type": "string",
"title": "Hint",
"description": "What to do about it."
}
},
"type": "object",
"required": [
"code",
"message",
"hint"
],
"title": "ErrorDetail"
},
"Fold": {
"properties": {
"limit": {
"type": "integer",
"title": "Limit",
"description": "About how many characters show before the platform cuts the post with 'more'."
},
"shown": {
"type": "integer",
"title": "Shown"
},
"text": {
"type": "string",
"title": "Text",
"description": "The part of the text that shows before the cut."
}
},
"type": "object",
"required": [
"limit",
"shown",
"text"
],
"title": "Fold"
},
"HTTPValidationError": {
"properties": {
"detail": {
"items": {
"$ref": "#/components/schemas/ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
},
"Health": {
"properties": {
"status": {
"type": "string",
"title": "Status"
},
"version": {
"type": "string",
"title": "Version",
"description": "Version of this API."
},
"engine_ref": {
"type": "string",
"title": "Engine Ref",
"description": "Commit of the postkitty engine this build runs."
},
"engine_version": {
"type": "string",
"title": "Engine Version"
},
"ffmpeg": {
"type": "string",
"title": "Ffmpeg"
},
"captions": {
"type": "boolean",
"title": "Captions",
"description": "True when this build can burn captions into a video."
},
"hdr": {
"type": "boolean",
"title": "Hdr",
"description": "True when this build can tone-map HDR video."
}
},
"type": "object",
"required": [
"status",
"version",
"engine_ref",
"engine_version",
"ffmpeg",
"captions",
"hdr"
],
"title": "Health"
},
"InputFile": {
"properties": {
"name": {
"type": "string",
"title": "Name",
"description": "The uploaded file's name, cleaned up. Shown as a label only."
},
"kind": {
"type": "string",
"title": "Kind"
},
"width": {
"type": "integer",
"title": "Width"
},
"height": {
"type": "integer",
"title": "Height"
},
"duration": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Duration"
},
"people": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "People",
"description": "People found in the file; null until the job has scanned it."
}
},
"type": "object",
"required": [
"name",
"kind",
"width",
"height"
],
"title": "InputFile"
},
"JobAccepted": {
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"status": {
"type": "string",
"title": "Status"
},
"links": {
"$ref": "#/components/schemas/Links"
}
},
"type": "object",
"required": [
"id",
"status",
"links"
],
"title": "JobAccepted"
},
"JobPlatformText": {
"properties": {
"label": {
"type": "string",
"title": "Label"
},
"ok": {
"type": "boolean",
"title": "Ok",
"description": "True when every part fits the limit and the hashtag and mention caps."
},
"enforcement": {
"type": "string",
"title": "Enforcement",
"description": "hard: the platform rejects text over the limit. recommendation: advice only."
},
"unit": {
"type": "string",
"title": "Unit",
"description": "How this platform counts: codepoints, x_weighted, graphemes, utf16 or threads."
},
"limit": {
"type": "integer",
"title": "Limit"
},
"count": {
"type": "integer",
"title": "Count",
"description": "Length of the longest part, in the platform's unit."
},
"overflow": {
"type": "integer",
"title": "Overflow",
"description": "How far the longest part is over the limit; 0 when it fits."
},
"split": {
"type": "boolean",
"title": "Split",
"description": "True when the text was split into a thread."
},
"parts": {
"items": {
"$ref": "#/components/schemas/TextPart"
},
"type": "array",
"title": "Parts"
},
"hashtags": {
"type": "integer",
"title": "Hashtags"
},
"mentions": {
"type": "integer",
"title": "Mentions"
},
"urls": {
"type": "integer",
"title": "Urls"
},
"fold": {
"anyOf": [
{
"$ref": "#/components/schemas/Fold"
},
{
"type": "null"
}
],
"description": "Null for X, which shows the whole post."
},
"notes": {
"items": {
"type": "string"
},
"type": "array",
"title": "Notes"
},
"files": {
"items": {
"type": "string"
},
"type": "array",
"title": "Files",
"description": "The text files written for this platform: post.txt, or thread.txt for a thread. Empty when the text is over a hard limit."
}
},
"type": "object",
"required": [
"label",
"ok",
"enforcement",
"unit",
"limit",
"count",
"overflow",
"split",
"parts",
"hashtags",
"mentions",
"urls",
"fold",
"notes",
"files"
],
"title": "JobPlatformText"
},
"JobStatus": {
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"status": {
"type": "string",
"title": "Status",
"description": "queued, running, done or failed."
},
"progress": {
"$ref": "#/components/schemas/Progress"
},
"created_at": {
"type": "string",
"title": "Created At"
},
"started_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Started At"
},
"finished_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Finished At"
},
"expires_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Expires At",
"description": "When the job and its files are deleted; null until it finishes."
},
"inputs": {
"items": {
"$ref": "#/components/schemas/InputFile"
},
"type": "array",
"title": "Inputs"
},
"captions": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Captions",
"description": "Name of the caption file burned into the video, when one was sent."
},
"targets": {
"items": {
"$ref": "#/components/schemas/TargetRow"
},
"type": "array",
"title": "Targets"
},
"text": {
"additionalProperties": {
"$ref": "#/components/schemas/JobPlatformText"
},
"type": "object",
"title": "Text"
},
"files": {
"items": {
"$ref": "#/components/schemas/ResultFile"
},
"type": "array",
"title": "Files"
},
"notes": {
"items": {
"type": "string"
},
"type": "array",
"title": "Notes"
},
"error": {
"anyOf": [
{
"$ref": "#/components/schemas/ErrorDetail"
},
{
"type": "null"
}
]
},
"links": {
"$ref": "#/components/schemas/Links"
}
},
"type": "object",
"required": [
"id",
"status",
"progress",
"created_at",
"started_at",
"finished_at",
"expires_at",
"inputs",
"captions",
"targets",
"text",
"files",
"notes",
"error",
"links"
],
"title": "JobStatus"
},
"LimitsView": {
"properties": {
"photos_per_job": {
"type": "integer",
"title": "Photos Per Job"
},
"videos_per_job": {
"type": "integer",
"title": "Videos Per Job"
},
"photo_max_bytes": {
"type": "integer",
"title": "Photo Max Bytes"
},
"video_max_bytes": {
"type": "integer",
"title": "Video Max Bytes"
},
"video_max_seconds": {
"type": "number",
"title": "Video Max Seconds"
},
"video_max_side": {
"type": "integer",
"title": "Video Max Side",
"description": "Longest allowed side of a video, in pixels."
},
"captions_max_bytes": {
"type": "integer",
"title": "Captions Max Bytes"
},
"image_max_pixels": {
"type": "integer",
"title": "Image Max Pixels"
},
"text_max_chars": {
"type": "integer",
"title": "Text Max Chars"
},
"queue_length": {
"type": "integer",
"title": "Queue Length",
"description": "Jobs that can wait in each line: one line for photo and text jobs, one for video jobs."
},
"job_timeout_seconds": {
"type": "integer",
"title": "Job Timeout Seconds"
},
"retention_minutes": {
"type": "integer",
"title": "Retention Minutes",
"description": "A job and its files are deleted this long after it finishes."
},
"rate_per_hour": {
"$ref": "#/components/schemas/RatePerHour"
},
"photo_types": {
"items": {
"type": "string"
},
"type": "array",
"title": "Photo Types"
},
"video_types": {
"items": {
"type": "string"
},
"type": "array",
"title": "Video Types"
},
"caption_types": {
"items": {
"type": "string"
},
"type": "array",
"title": "Caption Types"
},
"layouts": {
"items": {
"type": "string"
},
"type": "array",
"title": "Layouts"
}
},
"type": "object",
"required": [
"photos_per_job",
"videos_per_job",
"photo_max_bytes",
"video_max_bytes",
"video_max_seconds",
"video_max_side",
"captions_max_bytes",
"image_max_pixels",
"text_max_chars",
"queue_length",
"job_timeout_seconds",
"retention_minutes",
"rate_per_hour",
"photo_types",
"video_types",
"caption_types",
"layouts"
],
"title": "LimitsView"
},
"Links": {
"properties": {
"status": {
"type": "string",
"title": "Status"
},
"download": {
"type": "string",
"title": "Download"
}
},
"type": "object",
"required": [
"status",
"download"
],
"title": "Links"
},
"Platform": {
"properties": {
"name": {
"type": "string",
"title": "Name"
},
"label": {
"type": "string",
"title": "Label"
},
"text": {
"additionalProperties": {
"$ref": "#/components/schemas/Spec"
},
"type": "object",
"title": "Text"
},
"targets": {
"items": {
"$ref": "#/components/schemas/Target"
},
"type": "array",
"title": "Targets"
}
},
"type": "object",
"required": [
"name",
"label",
"text",
"targets"
],
"title": "Platform"
},
"PlatformList": {
"properties": {
"platforms": {
"items": {
"$ref": "#/components/schemas/Platform"
},
"type": "array",
"title": "Platforms"
}
},
"type": "object",
"required": [
"platforms"
],
"title": "PlatformList"
},
"PlatformText": {
"properties": {
"label": {
"type": "string",
"title": "Label"
},
"ok": {
"type": "boolean",
"title": "Ok",
"description": "True when every part fits the limit and the hashtag and mention caps."
},
"enforcement": {
"type": "string",
"title": "Enforcement",
"description": "hard: the platform rejects text over the limit. recommendation: advice only."
},
"unit": {
"type": "string",
"title": "Unit",
"description": "How this platform counts: codepoints, x_weighted, graphemes, utf16 or threads."
},
"limit": {
"type": "integer",
"title": "Limit"
},
"count": {
"type": "integer",
"title": "Count",
"description": "Length of the longest part, in the platform's unit."
},
"overflow": {
"type": "integer",
"title": "Overflow",
"description": "How far the longest part is over the limit; 0 when it fits."
},
"split": {
"type": "boolean",
"title": "Split",
"description": "True when the text was split into a thread."
},
"parts": {
"items": {
"$ref": "#/components/schemas/TextPart"
},
"type": "array",
"title": "Parts"
},
"hashtags": {
"type": "integer",
"title": "Hashtags"
},
"mentions": {
"type": "integer",
"title": "Mentions"
},
"urls": {
"type": "integer",
"title": "Urls"
},
"fold": {
"anyOf": [
{
"$ref": "#/components/schemas/Fold"
},
{
"type": "null"
}
],
"description": "Null for X, which shows the whole post."
},
"notes": {
"items": {
"type": "string"
},
"type": "array",
"title": "Notes"
}
},
"type": "object",
"required": [
"label",
"ok",
"enforcement",
"unit",
"limit",
"count",
"overflow",
"split",
"parts",
"hashtags",
"mentions",
"urls",
"fold",
"notes"
],
"title": "PlatformText"
},
"Progress": {
"properties": {
"stage": {
"type": "string",
"title": "Stage",
"description": "queued, start, scan, text, render, pack, done or failed."
},
"note": {
"type": "string",
"title": "Note"
},
"position": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Position",
"description": "Place in the queue while the job waits; 1 runs next."
}
},
"type": "object",
"required": [
"stage",
"note"
],
"title": "Progress"
},
"RatePerHour": {
"properties": {
"jobs": {
"type": "integer",
"title": "Jobs",
"description": "POST /v1/jobs."
},
"text_and_check": {
"type": "integer",
"title": "Text And Check",
"description": "POST /v1/text and POST /v1/check together."
},
"reads": {
"type": "integer",
"title": "Reads",
"description": "Every GET and DELETE under /v1."
}
},
"type": "object",
"required": [
"jobs",
"text_and_check",
"reads"
],
"title": "RatePerHour"
},
"ResultFile": {
"properties": {
"path": {
"type": "string",
"title": "Path",
"description": "Path under the job's ready folder, for example instagram/feed.jpg."
},
"url": {
"type": "string",
"title": "Url"
},
"platform": {
"type": "string",
"title": "Platform"
},
"kind": {
"type": "string",
"title": "Kind",
"description": "image, video or text."
},
"bytes": {
"type": "integer",
"title": "Bytes"
}
},
"type": "object",
"required": [
"path",
"url",
"platform",
"kind",
"bytes"
],
"title": "ResultFile"
},
"Spec": {
"properties": {
"value": {
"title": "Value"
},
"enforcement": {
"type": "string",
"title": "Enforcement",
"description": "hard blocks a file; recommendation only adds an advisory."
},
"unit": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Unit"
},
"source_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Source Url"
},
"source_scope": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Source Scope"
},
"checked_on": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Checked On"
},
"note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note"
}
},
"type": "object",
"required": [
"value",
"enforcement"
],
"title": "Spec"
},
"Target": {
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"label": {
"type": "string",
"title": "Label"
},
"kind": {
"type": "string",
"title": "Kind",
"description": "image, video or image_or_video."
},
"width": {
"type": "integer",
"title": "Width"
},
"height": {
"type": "integer",
"title": "Height"
},
"limits": {
"additionalProperties": {
"$ref": "#/components/schemas/Spec"
},
"type": "object",
"title": "Limits"
}
},
"type": "object",
"required": [
"id",
"label",
"kind",
"width",
"height",
"limits"
],
"title": "Target"
},
"TargetRow": {
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"platform": {
"type": "string",
"title": "Platform"
},
"kind": {
"type": "string",
"title": "Kind"
},
"status": {
"type": "string",
"title": "Status",
"description": "ready, repaired, failed or skipped. Only ready and repaired have a file."
},
"file": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "File"
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Url"
},
"cover": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Cover",
"description": "Cover frame of a video target."
},
"cover_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Cover Url"
},
"bytes": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Bytes"
},
"width": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Width"
},
"height": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Height"
},
"duration": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Duration"
},
"layout": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Layout"
},
"note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note"
},
"problems": {
"items": {
"type": "string"
},
"type": "array",
"title": "Problems",
"description": "Hard checks that failed, in plain words."
},
"advisories": {
"items": {
"type": "string"
},
"type": "array",
"title": "Advisories",
"description": "Recommendations the file does not meet."
},
"repairs": {
"items": {
"type": "string"
},
"type": "array",
"title": "Repairs",
"description": "What was fixed to make the file pass."
},
"reason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Reason",
"description": "Why a target was skipped."
},
"captions_shown": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Captions Shown",
"description": "How many captions were drawn into this file; null without a caption file."
}
},
"type": "object",
"required": [
"id",
"platform",
"kind",
"status",
"file",
"url",
"cover",
"cover_url",
"bytes",
"width",
"height",
"duration",
"layout",
"note",
"problems",
"advisories",
"repairs",
"reason",
"captions_shown"
],
"title": "TargetRow"
},
"TextPart": {
"properties": {
"text": {
"type": "string",
"title": "Text"
},
"count": {
"type": "integer",
"title": "Count"
}
},
"type": "object",
"required": [
"text",
"count"
],
"title": "TextPart"
},
"TextRequest": {
"properties": {
"text": {
"type": "string",
"title": "Text",
"description": "The post text."
},
"platforms": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Platforms",
"description": "Platform names or target ids. Leave out for every platform."
},
"split_threads": {
"type": "boolean",
"title": "Split Threads",
"description": "Split text over the limit into a numbered thread on X, Threads and Bluesky.",
"default": true
}
},
"type": "object",
"required": [
"text"
],
"title": "TextRequest"
},
"TextResult": {
"properties": {
"all_ok": {
"type": "boolean",
"title": "All Ok",
"description": "True when no platform with a hard limit is over it."
},
"platforms": {
"additionalProperties": {
"$ref": "#/components/schemas/PlatformText"
},
"type": "object",
"title": "Platforms"
}
},
"type": "object",
"required": [
"all_ok",
"platforms"
],
"title": "TextResult"
},
"ValidationError": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
}
}
}
}
{
"openapi": "3.1.0",
"info": {
"title": "postkitty API",
"summary": "One post in, a checked file for every social platform out.",
"description": "Send text, one photo or one landscape video and get back files sized, framed and checked for Instagram, TikTok, YouTube Shorts, X, LinkedIn, Threads, Bluesky and Facebook. Uploads only: the service never fetches a URL, never posts anywhere, and deletes each job 60 minutes after it finishes. Every error has the same shape: `{\"error\": {\"code\", \"message\", \"hint\"}}`. Guide: https://postkitty.mertkayacs.com/docs/",
"license": {
"name": "MIT"
},
"version": "1.0.0"
},
"paths": {
"/v1/health": {
"get": {
"tags": [
"service"
],
"summary": "Is the service up",
"operationId": "health_v1_health_get",
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Health"
}
}
}
}
}
}
},
"/v1/limits": {
"get": {
"tags": [
"service"
],
"summary": "Upload, queue and rate limits",
"operationId": "limits_view_v1_limits_get",
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/LimitsView"
}
}
}
}
}
}
},
"/v1/platforms": {
"get": {
"tags": [
"service"
],
"summary": "Every platform, its targets, sizes and limits",
"operationId": "platforms_v1_platforms_get",
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PlatformList"
}
}
}
}
}
}
},
"/v1/text": {
"post": {
"tags": [
"text"
],
"summary": "Count a text with each platform's own rule",
"operationId": "count_text_v1_text_post",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TextRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TextResult"
}