{
 "openapi": "3.1.0",
 "info": {
  "title": "SBIR Topics API",
  "version": "1.0.0",
  "description": "Match open U.S. SBIR/STTR topics to a company's past awards or to a capability paragraph. Automated matching only, not legal advice. Using the API means accepting the Terms. Free: 5 match calls a day per address; with a license key ($29/month): 500 a day. MCP server: POST /mcp.",
  "termsOfService": "https://sbirtopics.pages.dev/terms/",
  "contact": {
   "email": "support@figsheet.com"
  }
 },
 "servers": [
  {
   "url": "https://sbirtopics.pages.dev"
  }
 ],
 "externalDocs": {
  "url": "https://sbirtopics.pages.dev/developers/"
 },
 "components": {
  "securitySchemes": {
   "licenseKey": {
    "type": "http",
    "scheme": "bearer",
    "description": "License key from https://sbirtopics.pages.dev/pricing/ (optional)"
   }
  },
  "schemas": {
   "Error": {
    "type": "object",
    "required": [
     "error",
     "message"
    ],
    "properties": {
     "error": {
      "type": "string"
     },
     "message": {
      "type": "string"
     },
     "terms": {
      "type": "string"
     }
    }
   },
   "MatchItem": {
    "type": "object",
    "properties": {
     "topic_id": {
      "type": "integer"
     },
     "title": {
      "type": "string"
     },
     "agency": {
      "type": "string"
     },
     "branch": {
      "type": [
       "string",
       "null"
      ]
     },
     "program": {
      "type": [
       "string",
       "null"
      ]
     },
     "status": {
      "type": "string"
     },
     "open": {
      "type": [
       "string",
       "null"
      ],
      "format": "date"
     },
     "close": {
      "type": [
       "string",
       "null"
      ],
      "format": "date"
     },
     "score": {
      "type": "number",
      "minimum": 0,
      "maximum": 1
     },
     "shared_terms": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "closest_award": {
      "type": [
       "string",
       "null"
      ],
      "description": "For a firm match: its past award closest to the topic"
     },
     "url": {
      "type": "string",
      "description": "Official SBIR.gov topic page"
     },
     "page": {
      "type": [
       "string",
       "null"
      ],
      "description": "This site's page for the topic"
     }
    }
   },
   "Topic": {
    "type": "object",
    "properties": {
     "topic_id": {
      "type": "integer"
     },
     "title": {
      "type": "string"
     },
     "agency": {
      "type": "string"
     },
     "agency_name": {
      "type": "string"
     },
     "branch": {
      "type": [
       "string",
       "null"
      ]
     },
     "program": {
      "type": [
       "string",
       "null"
      ]
     },
     "phase": {
      "type": [
       "string",
       "null"
      ]
     },
     "topic_number": {
      "type": [
       "string",
       "null"
      ]
     },
     "solicitation_number": {
      "type": [
       "string",
       "null"
      ]
     },
     "status": {
      "type": "string",
      "enum": [
       "open",
       "pre-release"
      ]
     },
     "open": {
      "type": [
       "string",
       "null"
      ]
     },
     "close": {
      "type": [
       "string",
       "null"
      ]
     },
     "release": {
      "type": [
       "string",
       "null"
      ]
     },
     "url": {
      "type": "string"
     },
     "page": {
      "type": "string"
     },
     "summary": {
      "type": "string"
     },
     "description": {
      "type": "string"
     }
    }
   },
   "Match": {
    "type": "object",
    "required": [
     "id",
     "status",
     "results"
    ],
    "properties": {
     "id": {
      "type": "string",
      "format": "uuid"
     },
     "status": {
      "type": "string",
      "enum": [
       "working",
       "done",
       "error"
      ]
     },
     "kind": {
      "type": [
       "string",
       "null"
      ],
      "enum": [
       "firm",
       "text",
       null
      ]
     },
     "firm": {
      "type": "string"
     },
     "message": {
      "type": "string"
     },
     "results": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/MatchItem"
      }
     }
    }
   }
  }
 },
 "security": [
  {},
  {
   "licenseKey": []
  }
 ],
 "paths": {
  "/api/v1/match": {
   "post": {
    "operationId": "createMatch",
    "summary": "Start a match (counts toward the daily limit)",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "oneOf": [
         {
          "type": "object",
          "required": [
           "firm"
          ],
          "properties": {
           "firm": {
            "type": "string",
            "maxLength": 200,
            "description": "Company name as on its SBIR/STTR awards"
           }
          },
          "additionalProperties": false
         },
         {
          "type": "object",
          "required": [
           "text"
          ],
          "properties": {
           "text": {
            "type": "string",
            "maxLength": 2000,
            "description": "What the company does"
           }
          },
          "additionalProperties": false
         }
        ]
       }
      }
     }
    },
    "responses": {
     "202": {
      "description": "Queued; poll status_url",
      "headers": {
       "X-Terms": {
        "description": "Address of the Terms; using the API means accepting them",
        "schema": {
         "type": "string"
        }
       },
       "Location": {
        "schema": {
         "type": "string"
        }
       },
       "X-RateLimit-Limit": {
        "schema": {
         "type": "integer"
        }
       },
       "X-RateLimit-Remaining": {
        "schema": {
         "type": "integer"
        }
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "id": {
           "type": "string",
           "format": "uuid"
          },
          "status": {
           "type": "string",
           "const": "working"
          },
          "status_url": {
           "type": "string"
          },
          "tier": {
           "type": "string",
           "enum": [
            "free",
            "key"
           ]
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "401": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "413": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "503": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/api/v1/match/{id}": {
   "get": {
    "operationId": "getMatch",
    "summary": "Status and results of a match",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "The match",
      "headers": {
       "X-Terms": {
        "description": "Address of the Terms; using the API means accepting them",
        "schema": {
         "type": "string"
        }
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Match"
        }
       }
      }
     },
     "404": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/api/v1/topics": {
   "get": {
    "operationId": "listTopics",
    "summary": "Open and pre-release topics (without descriptions)",
    "parameters": [
     {
      "name": "status",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "open",
        "pre-release"
       ]
      }
     },
     {
      "name": "agency",
      "in": "query",
      "schema": {
       "type": "string"
      },
      "description": "Agency code, e.g. NSF"
     }
    ],
    "responses": {
     "200": {
      "description": "Topics",
      "headers": {
       "X-Terms": {
        "description": "Address of the Terms; using the API means accepting them",
        "schema": {
         "type": "string"
        }
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "updated": {
           "type": "string"
          },
          "count": {
           "type": "integer"
          },
          "topics": {
           "type": "array",
           "items": {
            "$ref": "#/components/schemas/Topic"
           }
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/api/v1/topics/{id}": {
   "get": {
    "operationId": "getTopic",
    "summary": "One topic with its description",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "The topic",
      "headers": {
       "X-Terms": {
        "description": "Address of the Terms; using the API means accepting them",
        "schema": {
         "type": "string"
        }
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Topic"
        }
       }
      }
     },
     "404": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  }
 }
}