openapi: 3.0.3
info:
  title: PromptEden Agent API
  version: "1.0"
  description: UI-free agent signup plus tenant-scoped REST API access for PromptEden account, project, monitor, and result data. API key authentication uses bearer tokens with the pe_ prefix.
servers:
  - url: https://app.prompteden.com/api/v1
security:
  - bearerApiKey: []
tags:
  - name: Agent
  - name: Account
  - name: Projects
  - name: Monitors
  - name: Results
paths:
  /agent/sign-up:
    post:
      tags: [Agent]
      summary: Create an agent workspace and one-time API key
      operationId: agentSignUp
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AgentSignUpRequest"
      responses:
        "201":
          description: Created agent workspace, optional first project, and one-time API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentSignUpResponse"
        "409":
          description: An account already exists for this email. Use /agent/sign-in.
        "429":
          description: Rate limit exceeded.
  /agent/sign-in:
    post:
      tags: [Agent]
      summary: Mint a one-time API key for an existing owner or admin
      operationId: agentSignIn
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AgentSignInRequest"
      responses:
        "200":
          description: New one-time API key for an existing API-enabled workspace.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentSignInResponse"
        "401":
          description: Invalid email or password.
        "403":
          description: Account is not an owner/admin or the workspace has no API access.
        "429":
          description: Rate limit exceeded.
  /agent/status:
    get:
      tags: [Agent]
      summary: Check API key readiness and agent surfaces
      operationId: getAgentStatus
      responses:
        "200":
          description: API key, workspace, and agent surface metadata.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentStatusResponse"
  /account:
    get:
      tags: [Account]
      summary: Get account metadata
      operationId: getAccount
      responses:
        "200":
          description: Team, plan, limits, usage, and credit metadata.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AccountResponse"
  /projects:
    get:
      tags: [Projects]
      summary: List projects
      operationId: listProjects
      responses:
        "200":
          description: Project list for the API key team.
          content:
            application/json:
              schema:
                type: object
                required: [projects]
                properties:
                  projects:
                    type: array
                    items:
                      $ref: "#/components/schemas/Project"
    post:
      tags: [Projects]
      summary: Create a project
      operationId: createProject
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ProjectCreate"
      responses:
        "201":
          description: Created project.
          content:
            application/json:
              schema:
                type: object
                required: [project]
                properties:
                  project:
                    $ref: "#/components/schemas/Project"
        "403":
          description: Plan limit reached or API access unavailable.
  /projects/{projectId}:
    get:
      tags: [Projects]
      summary: Get a project
      operationId: getProject
      parameters:
        - $ref: "#/components/parameters/ProjectId"
      responses:
        "200":
          description: Project detail for the API key team.
          content:
            application/json:
              schema:
                type: object
                required: [project]
                properties:
                  project:
                    $ref: "#/components/schemas/Project"
        "404":
          description: Project not found for this team.
  /monitors:
    get:
      tags: [Monitors]
      summary: List monitors
      operationId: listMonitors
      responses:
        "200":
          description: Monitor list for the API key team.
          content:
            application/json:
              schema:
                type: object
                required: [monitors]
                properties:
                  monitors:
                    type: array
                    items:
                      $ref: "#/components/schemas/Monitor"
    post:
      tags: [Monitors]
      summary: Create a monitor
      operationId: createMonitor
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/MonitorCreate"
      responses:
        "201":
          description: Created monitor.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Monitor"
        "403":
          description: Plan limit reached or selected providers require a paid plan.
  /monitors/{monitorId}/results:
    get:
      tags: [Results]
      summary: Get monitor results
      operationId: getMonitorResults
      parameters:
        - $ref: "#/components/parameters/MonitorId"
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 50
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
        - name: since
          in: query
          required: false
          schema:
            type: string
            format: date-time
      responses:
        "200":
          description: Monitor result list.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MonitorResultsResponse"
        "404":
          description: Monitor not found for this team.
components:
  securitySchemes:
    bearerApiKey:
      type: http
      scheme: bearer
      bearerFormat: pe_ API key
  parameters:
    ProjectId:
      name: projectId
      in: path
      required: true
      description: Project numeric id, UUID, or slug.
      schema:
        type: string
    MonitorId:
      name: monitorId
      in: path
      required: true
      description: Monitor UUID.
      schema:
        type: string
  schemas:
    AgentSignUpRequest:
      type: object
      required: [humanEmail, agentName]
      additionalProperties: false
      properties:
        humanEmail:
          type: string
          format: email
          description: Human owner email for the agent workspace.
        agentName:
          type: string
          minLength: 2
          maxLength: 120
        websiteUrl:
          type: string
          description: Optional first project website URL. Values without a scheme are normalized to https://.
        password:
          type: string
          minLength: 8
          description: Optional password for later /agent/sign-in key minting. If omitted, use the emailed or app password reset flow to claim the account.
    AgentSignInRequest:
      type: object
      required: [email, password]
      additionalProperties: false
      properties:
        email:
          type: string
          format: email
        password:
          type: string
        keyName:
          type: string
          maxLength: 120
    AgentSignUpResponse:
      type: object
      required: [status, apiKey, apiKeyPrefix, account, plan, next]
      properties:
        status:
          type: string
          enum: [created]
        apiKey:
          type: string
          description: One-time API key. Store it immediately; it is not returned again.
          example: pe_1234abcd5678efgh
        apiKeyPrefix:
          type: string
          description: Public key prefix used for display and revocation.
          example: pe_1234abcd5678efgh
        account:
          type: object
          additionalProperties: true
        plan:
          type: object
          additionalProperties: true
        project:
          $ref: "#/components/schemas/Project"
        next:
          type: object
          additionalProperties: true
    AgentSignInResponse:
      type: object
      required: [status, apiKey, apiKeyPrefix, account, plan, next]
      properties:
        status:
          type: string
          enum: [created]
        apiKey:
          type: string
          description: One-time API key. Store it immediately; it is not returned again.
          example: pe_1234abcd5678efgh
        apiKeyPrefix:
          type: string
          example: pe_1234abcd5678efgh
        account:
          type: object
          additionalProperties: true
        plan:
          type: object
          additionalProperties: true
        next:
          type: object
          additionalProperties: true
    AgentStatusResponse:
      type: object
      required: [status, key, account, surfaces]
      properties:
        status:
          type: string
          enum: [ready]
        key:
          type: object
          additionalProperties: true
        account:
          type: object
          additionalProperties: true
        surfaces:
          type: object
          additionalProperties:
            type: string
    AccountResponse:
      type: object
      additionalProperties: true
      properties:
        team:
          type: object
          additionalProperties: true
          properties:
            id:
              type: integer
            name:
              type: string
            slug:
              type: string
            createdAt:
              type: string
              format: date-time
              nullable: true
        plan:
          type: object
          additionalProperties: true
          properties:
            key:
              type: string
            name:
              type: string
            status:
              type: string
              nullable: true
            limits:
              type: object
              additionalProperties: true
              nullable: true
        usage:
          type: object
          additionalProperties: true
    Project:
      type: object
      additionalProperties: true
      properties:
        id:
          type: integer
        uuid:
          type: string
          format: uuid
        name:
          type: string
        slug:
          type: string
        websiteUrl:
          type: string
          format: uri
        language:
          type: string
        country:
          type: string
        createdAt:
          type: string
          format: date-time
          nullable: true
        updatedAt:
          type: string
          format: date-time
          nullable: true
    ProjectCreate:
      type: object
      required: [websiteUrl]
      additionalProperties: false
      properties:
        websiteUrl:
          type: string
          description: Website URL. Values without a scheme are normalized to https://.
        name:
          type: string
          minLength: 2
          maxLength: 150
        language:
          type: string
          default: en
        country:
          type: string
          default: US
    Monitor:
      type: object
      additionalProperties: true
      properties:
        id:
          type: integer
        uuid:
          type: string
          format: uuid
        name:
          type: string
        description:
          type: string
          nullable: true
        type:
          type: string
        status:
          type: string
        language:
          type: string
        country:
          type: string
        cadenceMinutes:
          type: integer
        project:
          type: object
          additionalProperties: true
        targets:
          type: array
          items:
            type: object
            additionalProperties: true
        prompts:
          type: array
          items:
            type: object
            additionalProperties: true
    MonitorCreate:
      type: object
      required: [name, type, language, country, cadenceMinutes, promptInstructions, targets]
      additionalProperties: true
      properties:
        projectId:
          type: integer
          description: Required unless projectSlug is supplied.
        projectSlug:
          type: string
          description: Required unless projectId is supplied.
        name:
          type: string
        type:
          type: string
          enum: [search, api, scrape]
        description:
          type: string
        language:
          type: string
        country:
          type: string
        cadenceMinutes:
          type: integer
          minimum: 1440
        promptInstructions:
          type: string
        targets:
          type: array
          items:
            type: object
            required: [providerKey]
            additionalProperties: true
            properties:
              providerKey:
                type: string
              model:
                type: string
              displayName:
                type: string
    MonitorResultsResponse:
      type: object
      additionalProperties: true
      properties:
        monitor:
          type: object
          additionalProperties: true
        results:
          type: array
          items:
            $ref: "#/components/schemas/MonitorResult"
        pagination:
          type: object
          additionalProperties: true
    MonitorResult:
      type: object
      additionalProperties: true
      properties:
        id:
          type: string
          format: uuid
        createdAt:
          type: string
          format: date-time
          nullable: true
        provider:
          type: string
          nullable: true
        model:
          type: string
          nullable: true
        providerDisplayName:
          type: string
          nullable: true
        prompt:
          type: object
          additionalProperties: true
        snippet:
          type: string
          nullable: true
        response:
          type: string
          nullable: true
        mentions:
          type: integer
        mentionScore:
          type: number
          nullable: true
        runId:
          type: integer
        runCompletedAt:
          type: string
          format: date-time
          nullable: true