{
  "openapi": "3.1.0",
  "info": {
    "title": "Sentie REST API",
    "summary": "Programmatic access to Sentie custom AI agents.",
    "description": "Sentie builds custom AI agents for businesses (a core agent plus specialized agents configured to each customer's data, tools, playbooks, and voice). This API is the canonical surface for managing assessments, agents, capabilities, integrations, and pricing programmatically. The sentie CLI wraps this API.\n\nNote: This is the published API contract as of 2026-05-21 (agents-first rebrand). The real software-team implementation is being verified. Bearer auth, the api.sentie.io/v1 base, and the endpoint surface below are the locked design defaults; some details may be refined at launch.",
    "version": "1.0.0",
    "contact": {
      "name": "Sentie Developers",
      "url": "https://sentie.io/developers",
      "email": "developers@sentie.io"
    },
    "license": {
      "name": "Sentie Terms of Service",
      "url": "https://sentie.io/terms"
    }
  },
  "servers": [
    {
      "url": "https://api.sentie.io/v1",
      "description": "Production REST API."
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "tags": [
    { "name": "assessments", "description": "Free custom AI agent assessment flow." },
    { "name": "agents", "description": "Custom AI agents configured for a tenant." },
    { "name": "capabilities", "description": "Catalog of agent capability categories." },
    { "name": "integrations", "description": "Catalog of supported tool integrations." },
    { "name": "pricing", "description": "Current Sentie pricing tiers." }
  ],
  "paths": {
    "/assessments": {
      "post": {
        "tags": ["assessments"],
        "operationId": "startAssessment",
        "summary": "Start a free custom AI agent assessment",
        "description": "Submit a company name, industry, and the workflows you want a custom AI agent to handle. Returns an assessment id; a Sentie Success Manager will scope it with the customer and configure the resulting agents.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/AssessmentCreate" }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Assessment created.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Assessment" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/assessments/{id}": {
      "get": {
        "tags": ["assessments"],
        "operationId": "getAssessment",
        "summary": "Retrieve an in-progress assessment",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Assessment retrieved.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Assessment" }
              }
            }
          },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/agents": {
      "get": {
        "tags": ["agents"],
        "operationId": "listAgents",
        "summary": "List custom AI agents on the current tenant",
        "responses": {
          "200": {
            "description": "Agents listed.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/Agent" }
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": ["agents"],
        "operationId": "createAgent",
        "summary": "Configure a new specialized agent",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/AgentCreate" }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Agent configured.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Agent" }
              }
            }
          }
        }
      }
    },
    "/agents/{id}": {
      "get": {
        "tags": ["agents"],
        "operationId": "getAgent",
        "summary": "Retrieve a specific custom AI agent",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Agent retrieved.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Agent" }
              }
            }
          },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/capabilities": {
      "get": {
        "tags": ["capabilities"],
        "operationId": "listCapabilities",
        "summary": "List available agent capability categories",
        "responses": {
          "200": {
            "description": "Capabilities listed.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/Capability" }
                }
              }
            }
          }
        }
      }
    },
    "/integrations": {
      "get": {
        "tags": ["integrations"],
        "operationId": "listIntegrations",
        "summary": "List supported tool integrations",
        "parameters": [
          {
            "name": "category",
            "in": "query",
            "required": false,
            "schema": { "type": "string" },
            "description": "Optional category filter (crm, helpdesk, accounting, scheduling, etc.)."
          }
        ],
        "responses": {
          "200": {
            "description": "Integrations listed.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/Integration" }
                }
              }
            }
          }
        }
      }
    },
    "/pricing": {
      "get": {
        "tags": ["pricing"],
        "operationId": "getPricing",
        "summary": "Read current Sentie pricing",
        "responses": {
          "200": {
            "description": "Pricing returned.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Pricing" }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "Token",
        "description": "Bearer token in the Authorization header. Tokens are generated and scoped from the Sentie dashboard."
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "Missing or invalid bearer token.",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" }
          }
        }
      },
      "NotFound": {
        "description": "The requested resource does not exist on this tenant.",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" }
          }
        }
      }
    },
    "schemas": {
      "AssessmentCreate": {
        "type": "object",
        "required": ["company", "industry", "use_cases"],
        "properties": {
          "company": { "type": "string", "description": "Customer company name." },
          "industry": {
            "type": "string",
            "description": "Industry slug. Matches an entry on sentie.io/industries (e.g., hvac, plumbing, ecommerce)."
          },
          "use_cases": {
            "type": "array",
            "items": { "type": "string" },
            "description": "Workflows the custom AI agents should handle (e.g., quote-follow-up, dispatch-triage)."
          }
        }
      },
      "Assessment": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "company": { "type": "string" },
          "industry": { "type": "string" },
          "use_cases": {
            "type": "array",
            "items": { "type": "string" }
          },
          "status": {
            "type": "string",
            "enum": ["scoping", "ready-to-deploy", "deployed", "closed"]
          },
          "scoped_agents": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/Agent" }
          },
          "success_manager": {
            "type": "object",
            "properties": {
              "name": { "type": "string" },
              "email": { "type": "string", "format": "email" }
            }
          },
          "created_at": { "type": "string", "format": "date-time" }
        }
      },
      "AgentCreate": {
        "type": "object",
        "required": ["capability_id"],
        "properties": {
          "capability_id": {
            "type": "string",
            "description": "Capability category id (see /capabilities)."
          },
          "integrations": {
            "type": "array",
            "items": { "type": "string" },
            "description": "Integration ids to bind the agent to (see /integrations)."
          },
          "playbook": {
            "type": "string",
            "description": "Free-form description of the workflow the agent should follow."
          }
        }
      },
      "Agent": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "tenant_id": { "type": "string" },
          "kind": {
            "type": "string",
            "enum": ["core", "specialized"]
          },
          "capability": { "$ref": "#/components/schemas/Capability" },
          "integrations": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/Integration" }
          },
          "playbook": { "type": "string" },
          "action_log_count": { "type": "integer" },
          "created_at": { "type": "string", "format": "date-time" }
        }
      },
      "Capability": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" },
          "category": {
            "type": "string",
            "description": "Function category (sales, support, ops, finance, scheduling, marketing, etc.)."
          },
          "description": { "type": "string" }
        }
      },
      "Integration": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" },
          "category": { "type": "string" },
          "actions": {
            "type": "array",
            "items": { "type": "string" }
          },
          "auth_type": {
            "type": "string",
            "enum": ["oauth2", "api-key", "service-account"]
          }
        }
      },
      "Pricing": {
        "type": "object",
        "properties": {
          "currency": { "type": "string", "example": "USD" },
          "tiers": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": { "type": "string" },
                "name": { "type": "string" },
                "monthly_price": { "type": "number" },
                "monthly_credits": { "type": "integer", "nullable": true },
                "includes": {
                  "type": "array",
                  "items": { "type": "string" }
                }
              }
            }
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "code": { "type": "string" },
          "message": { "type": "string" },
          "documentation_url": { "type": "string", "format": "uri" }
        }
      }
    }
  }
}