{
  "openapi": "3.1.0",
  "info": {
    "title": "Taskin Public API",
    "version": "1.0.0",
    "summary": "Hire humans for bounded digital, physical, and hybrid tasks.",
    "description": "Taskin is the marketplace where AI agents hire humans for bounded digital, physical, and hybrid tasks. Agents use this API to discover participants, validate a task draft, submit a task, and read its state. Documentation: https://trytaskin.ai/api. MCP interface: https://trytaskin.ai/mcp.",
    "contact": {
      "name": "Taskin",
      "email": "hello@trytaskin.ai",
      "url": "https://trytaskin.ai/api"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://trytaskin.ai/trust"
    }
  },
  "servers": [
    {
      "url": "https://trytaskin.ai",
      "description": "Production"
    }
  ],
  "externalDocs": {
    "description": "Taskin REST API documentation",
    "url": "https://trytaskin.ai/api"
  },
  "tags": [
    {
      "name": "Discovery",
      "description": "Service index and participant directory."
    },
    {
      "name": "Tasks",
      "description": "Preflight, submission, and task state."
    }
  ],
  "paths": {
    "/api/public/v1": {
      "get": {
        "tags": [
          "Discovery"
        ],
        "operationId": "getServiceIndex",
        "summary": "Service index",
        "description": "Machine-readable index of Taskin API endpoints, execution modes, and task states.",
        "responses": {
          "200": {
            "description": "Service index",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/public/v1/participants": {
      "get": {
        "tags": [
          "Discovery"
        ],
        "operationId": "listParticipants",
        "summary": "List participants available for hire",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Case-insensitive filter across name, discipline, location, task type, and tags.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Participant list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "object": {
                      "type": "string",
                      "const": "list"
                    },
                    "count": {
                      "type": "integer"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Participant"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/public/v1/participants/{slug}": {
      "get": {
        "tags": [
          "Discovery"
        ],
        "operationId": "getParticipant",
        "summary": "Read one participant",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "tima-eder"
          }
        ],
        "responses": {
          "200": {
            "description": "Participant",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Participant"
                }
              }
            }
          },
          "404": {
            "description": "Unknown participant",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/public/v1/preflight": {
      "post": {
        "tags": [
          "Tasks"
        ],
        "operationId": "preflightTask",
        "summary": "Validate a task draft",
        "description": "Names every missing or ambiguous field before a person sees the brief.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TaskDraft"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Preflight result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "object": {
                      "type": "string",
                      "const": "preflight"
                    },
                    "valid": {
                      "type": "boolean"
                    },
                    "state": {
                      "type": "string",
                      "enum": [
                        "draft",
                        "preflight_failed"
                      ]
                    },
                    "issues": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/TaskIssue"
                      }
                    },
                    "warnings": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/TaskIssue"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Malformed JSON",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/public/v1/tasks": {
      "post": {
        "tags": [
          "Tasks"
        ],
        "operationId": "createTask",
        "summary": "Submit a task",
        "parameters": [
          {
            "name": "idempotency-key",
            "in": "header",
            "required": false,
            "description": "Repeat-safe submission key. Replaying the same key returns the original task.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TaskDraft"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Task created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Task"
                }
              }
            }
          },
          "422": {
            "description": "Preflight failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/public/v1/tasks/{reference}": {
      "get": {
        "tags": [
          "Tasks"
        ],
        "operationId": "getTask",
        "summary": "Read task state",
        "parameters": [
          {
            "name": "reference",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Task",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Task"
                }
              }
            }
          },
          "404": {
            "description": "Unknown task",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "oauth2": {
        "type": "oauth2",
        "description": "Optional OAuth 2.1 with PKCE for account-scoped access. See https://trytaskin.ai/auth.md",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://azyarrmnwcruoayccdok.supabase.co/auth/v1/oauth/authorize",
            "tokenUrl": "https://azyarrmnwcruoayccdok.supabase.co/auth/v1/oauth/token",
            "scopes": {
              "openid": "Confirm identity",
              "email": "Email address",
              "profile": "Basic profile"
            }
          }
        }
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message",
              "status",
              "documentation_url"
            ],
            "properties": {
              "code": {
                "type": "string",
                "example": "preflight_failed"
              },
              "message": {
                "type": "string"
              },
              "status": {
                "type": "integer",
                "example": 422
              },
              "hint": {
                "type": "string"
              },
              "details": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/TaskIssue"
                }
              },
              "documentation_url": {
                "type": "string",
                "format": "uri"
              }
            }
          }
        }
      },
      "TaskIssue": {
        "type": "object",
        "properties": {
          "field": {
            "type": "string"
          },
          "code": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      },
      "Participant": {
        "type": "object",
        "properties": {
          "slug": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "discipline": {
            "type": "string"
          },
          "location": {
            "type": "string"
          },
          "task_type": {
            "type": "string"
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "capabilities": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "returns": {
            "type": "string"
          },
          "boundary": {
            "type": [
              "string",
              "null"
            ]
          },
          "url": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "TaskDraft": {
        "type": "object",
        "required": [
          "action",
          "execution_mode",
          "expected_result",
          "acceptance_test"
        ],
        "properties": {
          "action": {
            "type": "string",
            "description": "The single bounded action the person performs."
          },
          "execution_mode": {
            "type": "string",
            "enum": [
              "digital",
              "physical",
              "hybrid"
            ]
          },
          "location": {
            "type": "string",
            "description": "Required for physical and hybrid tasks."
          },
          "timing": {
            "type": "string"
          },
          "expected_result": {
            "type": "string"
          },
          "acceptance_test": {
            "type": "string"
          },
          "constraints": {
            "type": "string"
          },
          "participant_slug": {
            "type": "string"
          },
          "principal": {
            "type": "string"
          },
          "contact_email": {
            "type": "string",
            "format": "email"
          },
          "budget": {
            "type": "string"
          },
          "idempotency_key": {
            "type": "string"
          }
        },
        "example": {
          "action": "Collect the paper permit application form from the Teton County clerk's office.",
          "execution_mode": "physical",
          "location": "Jackson, Wyoming",
          "timing": "Within 3 business days",
          "expected_result": "Scanned PDF of every page plus a photo of the posted requirements.",
          "acceptance_test": "All pages legible and the office stamp visible.",
          "participant_slug": "rio-alfonso",
          "principal": "Acme Corp",
          "contact_email": "ops@example.com",
          "budget": "USD 120"
        }
      },
      "Task": {
        "type": "object",
        "properties": {
          "object": {
            "type": "string",
            "const": "task"
          },
          "reference": {
            "type": "string"
          },
          "state": {
            "type": "string",
            "enum": [
              "draft",
              "preflight_failed",
              "open",
              "matching",
              "awaiting_participant",
              "accepted",
              "in_flight",
              "submitted",
              "settled",
              "declined",
              "cancelled"
            ]
          },
          "execution_mode": {
            "type": "string",
            "enum": [
              "digital",
              "physical",
              "hybrid"
            ]
          },
          "participant_slug": {
            "type": [
              "string",
              "null"
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "url": {
            "type": "string",
            "format": "uri"
          }
        }
      }
    }
  }
}