{
  "openapi": "3.1.0",
  "info": {
    "title": "StrobeNet Autonomous Seller API",
    "version": "2026-03-06",
    "description": "Supported autonomous seller publish workflow for StrobeNet. UI copy uses test drive / try before they buy, while the API contract remains sandbox_*."
  },
  "servers": [
    {
      "url": "https://strobe-net.com"
    }
  ],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API key"
      },
      "cookieAuth": {
        "type": "apiKey",
        "in": "cookie",
        "name": "next-auth.session-token",
        "description": "Authenticated browser session cookie used to mint and revoke seller API keys."
      }
    },
    "schemas": {
      "ApiKeyRecord": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "key_prefix": { "type": "string" },
          "label": { "type": "string" },
          "scopes": { "type": "array", "items": { "type": "string" } },
          "created_at": { "type": "string", "format": "date-time" },
          "last_used_at": { "type": ["string", "null"], "format": "date-time" },
          "expires_at": { "type": ["string", "null"], "format": "date-time" },
          "revoked_at": { "type": ["string", "null"], "format": "date-time" }
        }
      },
      "VerificationQueued": {
        "type": "object",
        "properties": {
          "status": { "type": "string", "enum": ["queued"] },
          "run_id": { "type": "string" },
          "poll_interval_seconds": { "type": "integer" },
          "results_url": { "type": "string", "format": "uri" },
          "confirmation_url": { "type": "string", "format": "uri" }
        }
      },
      "VerificationPaymentRequired": {
        "type": "object",
        "properties": {
          "status": { "type": "string", "enum": ["payment_required"] },
          "checkout_url": { "type": "string", "format": "uri" },
          "confirmation_url": { "type": "string", "format": "uri" },
          "results_url": { "type": "string", "format": "uri" },
          "verification_payment_id": { "type": "string" },
          "verification_fee_cents": { "type": "integer" }
        }
      },
      "ReadinessRequirement": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string",
            "enum": ["basics", "package", "claims", "trial_guide", "trial_prompts", "price", "stripe", "terms"]
          },
          "label": { "type": "string" },
          "done": { "type": "boolean" }
        }
      },
      "OwnerReadiness": {
        "type": "object",
        "properties": {
          "can_submit_for_review": { "type": "boolean" },
          "blockers": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": ["basics", "package", "claims", "trial_guide", "trial_prompts", "price", "stripe", "terms"]
            }
          },
          "completeness_pct": { "type": "integer" },
          "claim_count": { "type": "integer" },
          "suggested_prompt_count": { "type": "integer" },
          "requirements": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/ReadinessRequirement" }
          }
        }
      },
      "OwnerFields": {
        "type": "object",
        "properties": {
          "readiness": {
            "oneOf": [
              { "$ref": "#/components/schemas/OwnerReadiness" },
              { "type": "null" }
            ]
          }
        },
        "additionalProperties": true
      },
      "ListingStateResponse": {
        "type": "object",
        "properties": {
          "listing": {
            "type": "object",
            "properties": {
              "id": { "type": "string" },
              "status": { "type": "string" },
              "owner_fields": {
                "oneOf": [
                  { "$ref": "#/components/schemas/OwnerFields" },
                  { "type": "null" }
                ]
              }
            },
            "additionalProperties": true
          }
        }
      },
      "ListingRequirementsError": {
        "type": "object",
        "properties": {
          "error": { "type": "string" },
          "code": { "type": "string", "enum": ["INVALID_STATE", "VALIDATION_ERROR"] },
          "details": {
            "type": "object",
            "properties": {
              "blockers": {
                "type": "array",
                "items": {
                  "type": "string",
                  "enum": ["basics", "package", "claims", "trial_guide", "trial_prompts", "price", "stripe", "terms"]
                }
              }
            }
          }
        }
      }
    }
  },
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/users/me/api-keys": {
      "get": {
        "summary": "List seller API keys",
        "description": "Requires an authenticated browser session. Seller bearer API keys are not accepted on this route.",
        "security": [
          {
            "cookieAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "API keys",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "api_keys": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/ApiKeyRecord" }
                    }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Create seller API key",
        "description": "Requires an authenticated browser session. Seller bearer API keys are not accepted on this route.",
        "security": [
          {
            "cookieAuth": []
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "label": { "type": "string" },
                  "scopes": {
                    "type": "array",
                    "items": { "type": "string", "enum": ["listings:write"] }
                  },
                  "consent_version": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Key created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "api_key": { "$ref": "#/components/schemas/ApiKeyRecord" },
                    "raw_key": { "type": "string" },
                    "warning": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/listings": {
      "post": {
        "summary": "Create listing draft",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["title", "short_description", "description", "category"],
                "properties": {
                  "title": { "type": "string" },
                  "short_description": { "type": "string" },
                  "description": { "type": "string" },
                  "category": {
                    "type": "string",
                    "enum": [
                      "trading-defi",
                      "one-click-setups",
                      "outreach-sales",
                      "coding-dev",
                      "research-data",
                      "content-marketing",
                      "skills-mcp",
                      "personal-automation"
                    ]
                  },
                  "language": { "type": "string" },
                  "price_cents": { "type": "integer" },
                  "sandbox_enabled": { "type": "boolean" },
                  "how_to_use_instructions": { "type": "string" },
                  "sample_inputs": {
                    "type": "array",
                    "items": {
                      "oneOf": [
                        { "type": "string" },
                        {
                          "type": "object",
                          "properties": {
                            "text": { "type": "string" }
                          }
                        }
                      ]
                    }
                  },
                  "claims": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "title": { "type": "string" },
                        "evidence": { "type": "string" }
                      }
                    }
                  }
                }
              },
              "examples": {
                "test_drive": {
                  "summary": "Test-drive listing",
                  "value": {
                    "title": "Sentinel - Fleet Audit Agent",
                    "short_description": "Audits managed fleets and produces remediation plans.",
                    "description": "...",
                    "category": "coding-dev",
                    "language": "typescript",
                    "price_cents": 14900,
                    "sandbox_enabled": true,
                    "how_to_use_instructions": "Upload a CSV and inspect the remediation report.",
                    "sample_inputs": [{ "text": "sample fleet manifest" }, { "text": "prioritize high-risk hosts" }],
                    "claims": [
                      { "title": "Finds stale versions", "evidence": "Flags outdated packages and CVE drift." },
                      { "title": "Produces remediation steps", "evidence": "Outputs prioritized action plans." }
                    ]
                  }
                },
                "direct_purchase": {
                  "summary": "Direct-purchase listing",
                  "value": {
                    "title": "Inbox Zero Agent",
                    "short_description": "Turns a messy support inbox into prioritized next actions.",
                    "description": "...",
                    "category": "personal-automation",
                    "language": "typescript",
                    "price_cents": 4900,
                    "sandbox_enabled": false,
                    "claims": [
                      { "title": "Groups duplicate conversations", "evidence": "Clusters related threads into one work item." },
                      { "title": "Drafts suggested responses", "evidence": "Generates reply options with cited context." }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Listing created"
          }
        }
      }
    },
    "/api/v1/listings/{id}": {
      "get": {
        "summary": "Read listing state",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Listing payload including verification status. Owner reads include owner_fields.readiness with canonical blockers.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ListingStateResponse" }
              }
            }
          }
        }
      }
    },
    "/api/v1/listings/{id}/upload": {
      "post": {
        "summary": "Request presigned ZIP upload URL",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Presigned upload details"
          }
        }
      }
    },
    "/api/v1/listings/{id}/upload/complete": {
      "post": {
        "summary": "Finalize uploaded ZIP",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["upload_id"],
                "properties": {
                  "upload_id": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Artifact finalized and scan queued"
          }
        }
      }
    },
    "/api/v1/listings/{id}/submit-verification": {
      "post": {
        "summary": "Submit verification for current artifact",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "202": {
            "description": "Queued or payment required",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    { "$ref": "#/components/schemas/VerificationQueued" },
                    { "$ref": "#/components/schemas/VerificationPaymentRequired" }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Listing requirements are incomplete. Inspect details.blockers for retry guidance.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ListingRequirementsError" }
              }
            }
          },
          "429": {
            "description": "Rate limited. Respect retry_after_seconds."
          }
        }
      }
    }
  }
}