{
	"openapi": "3.0.3",
	"info": {
		"title": "VeilStrat Pro API",
		"description": "Scalpel REST for VeilStrat Pro. Authenticate with a team `vs_` API key. Firehose webhooks are outbound (configure in Settings → Webhooks) — not part of this REST surface.",
		"version": "1.0.0"
	},
	"servers": [
		{
			"url": "https://app.veilstrat.com",
			"description": "Production"
		},
		{
			"url": "http://localhost:3000",
			"description": "Local development"
		}
	],
	"tags": [
		{
			"name": "Health"
		},
		{
			"name": "Stats"
		},
		{
			"name": "Filters"
		},
		{
			"name": "Companies"
		},
		{
			"name": "Slices"
		}
	],
	"paths": {
		"/api/v1/health": {
			"get": {
				"tags": [
					"Health"
				],
				"summary": "GET health",
				"description": "Uptime check. Exempt from request budget.",
				"operationId": "getHealth",
				"security": [
					{
						"bearerAuth": []
					}
				],
				"responses": {
					"200": {
						"description": "API and database dependency OK",
						"content": {
							"application/json": {
								"schema": {
									"$ref": "#/components/schemas/HealthOk"
								},
								"example": {
									"status": "ok",
									"apiVersion": "v1",
									"timestamp": "2026-08-20T00:00:00.000Z"
								}
							}
						}
					}
				}
			}
		},
		"/api/v1/stats": {
			"get": {
				"tags": [
					"Stats"
				],
				"summary": "GET stats",
				"description": "Usage buckets and static limits. Exempt from request budget.",
				"operationId": "getStats",
				"security": [
					{
						"bearerAuth": []
					}
				],
				"responses": {
					"200": {
						"description": "Usage snapshot",
						"content": {
							"application/json": {
								"schema": {
									"$ref": "#/components/schemas/UsageSnapshot"
								},
								"example": {
									"period": {
										"monthStart": "2026-08-01T00:00:00.000Z",
										"dayStart": "2026-08-20"
									},
									"rateLimits": {
										"perMinute": {
											"limit": 20,
											"used": 0,
											"remaining": 20,
											"resetUnix": 1724112060
										},
										"dailyRequests": {
											"limit": 300,
											"used": 12,
											"remaining": 288,
											"resetUnix": 1724198400
										},
										"monthlyRequests": {
											"limit": 3000,
											"used": 40,
											"remaining": 2960,
											"resetUnix": 1725148800
										},
										"monthlyRecords": {
											"limit": 3000,
											"used": 100,
											"remaining": 2900,
											"resetUnix": 1725148800
										},
										"monthlyPageTurns": {
											"limit": 200,
											"used": 2,
											"remaining": 198,
											"resetUnix": 1725148800
										},
										"dailyCompanyDetail": {
											"limit": 100,
											"used": 1,
											"remaining": 99,
											"resetUnix": 1724198400
										}
									},
									"staticLimits": {
										"pageSizeMax": 50,
										"querySetRecordsMax": 500
									}
								}
							}
						}
					}
				}
			}
		},
		"/api/v1/filters": {
			"get": {
				"tags": [
					"Filters"
				],
				"summary": "GET filters",
				"description": "Catalog of enums and match rules for company search and slice search.",
				"operationId": "getFilters",
				"security": [
					{
						"bearerAuth": []
					}
				],
				"responses": {
					"200": {
						"description": "Filter catalog",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"additionalProperties": true
								}
							}
						}
					}
				}
			}
		},
		"/api/v1/companies": {
			"post": {
				"tags": [
					"Companies"
				],
				"summary": "POST company search",
				"description": "`signal_query` is required. Returns companies with signal overlays.",
				"operationId": "postCompanySearch",
				"security": [
					{
						"bearerAuth": []
					}
				],
				"requestBody": {
					"required": true,
					"content": {
						"application/json": {
							"schema": {
								"$ref": "#/components/schemas/CompanySearchRequest"
							},
							"example": {
								"signal_query": "signal:hiring:30d",
								"countries": [
									"US"
								],
								"page": 1,
								"pageSize": 50
							}
						}
					}
				},
				"responses": {
					"200": {
						"description": "Search page",
						"content": {
							"application/json": {
								"schema": {
									"$ref": "#/components/schemas/CompanySearchResponse"
								},
								"example": {
									"companies": [
										{
											"id": "4066c846-48ea-403a-97b1-fd60503fdb97",
											"name": "Example Co",
											"domain": "example.com"
										}
									],
									"page": 1,
									"pageSize": 50,
									"total": 1,
									"totalPages": 1
								}
							}
						}
					}
				}
			}
		},
		"/api/v1/companies/{id}": {
			"get": {
				"tags": [
					"Companies"
				],
				"summary": "GET company dossier",
				"description": "Signal dossier for a company UUID.",
				"operationId": "getCompanyDossier",
				"security": [
					{
						"bearerAuth": []
					}
				],
				"parameters": [
					{
						"name": "id",
						"in": "path",
						"required": true,
						"description": "Company UUID",
						"schema": {
							"type": "string",
							"format": "uuid"
						}
					}
				],
				"responses": {
					"200": {
						"description": "Company dossier",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"additionalProperties": true
								},
								"example": {
									"id": "4066c846-48ea-403a-97b1-fd60503fdb97",
									"name": "Example Co",
									"domain": "example.com",
									"signals": []
								}
							}
						}
					}
				}
			}
		},
		"/api/v1/slices": {
			"get": {
				"tags": [
					"Slices"
				],
				"summary": "GET slice search",
				"description": "Requires `slice` plus at least one filter.",
				"operationId": "getSliceSearch",
				"security": [
					{
						"bearerAuth": []
					}
				],
				"parameters": [
					{
						"name": "slice",
						"in": "query",
						"required": true,
						"schema": {
							"type": "string"
						},
						"example": "ai-sdr-hiring"
					},
					{
						"name": "countries",
						"in": "query",
						"required": false,
						"schema": {
							"type": "string"
						},
						"example": "US"
					},
					{
						"name": "scoreMin",
						"in": "query",
						"required": false,
						"schema": {
							"type": "number"
						},
						"example": 70
					}
				],
				"responses": {
					"200": {
						"description": "Slice search page",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"additionalProperties": true
								}
							}
						}
					}
				}
			}
		}
	},
	"components": {
		"securitySchemes": {
			"bearerAuth": {
				"type": "http",
				"scheme": "bearer",
				"bearerFormat": "vs_",
				"description": "Pro team API key from Settings → API (`vs_…`)."
			}
		},
		"schemas": {
			"HealthOk": {
				"type": "object",
				"required": [
					"status",
					"apiVersion",
					"timestamp"
				],
				"properties": {
					"status": {
						"type": "string",
						"enum": [
							"ok"
						]
					},
					"apiVersion": {
						"type": "string",
						"enum": [
							"v1"
						]
					},
					"timestamp": {
						"type": "string",
						"format": "date-time"
					}
				}
			},
			"RateLimitBucket": {
				"type": "object",
				"required": [
					"limit",
					"used",
					"remaining",
					"resetUnix"
				],
				"properties": {
					"limit": {
						"type": "integer"
					},
					"used": {
						"type": "integer"
					},
					"remaining": {
						"type": "integer"
					},
					"resetUnix": {
						"type": "integer"
					},
					"note": {
						"type": "string"
					}
				}
			},
			"UsageSnapshot": {
				"type": "object",
				"required": [
					"period",
					"rateLimits",
					"staticLimits"
				],
				"properties": {
					"period": {
						"type": "object",
						"properties": {
							"monthStart": {
								"type": "string",
								"format": "date-time"
							},
							"dayStart": {
								"type": "string"
							}
						}
					},
					"rateLimits": {
						"type": "object",
						"additionalProperties": {
							"$ref": "#/components/schemas/RateLimitBucket"
						}
					},
					"staticLimits": {
						"type": "object",
						"properties": {
							"pageSizeMax": {
								"type": "integer"
							},
							"querySetRecordsMax": {
								"type": "integer"
							}
						}
					}
				}
			},
			"CompanySearchRequest": {
				"type": "object",
				"required": [
					"signal_query"
				],
				"properties": {
					"signal_query": {
						"type": "string",
						"description": "Required signal mix query."
					},
					"countries": {
						"type": "array",
						"items": {
							"type": "string"
						}
					},
					"page": {
						"type": "integer",
						"minimum": 1
					},
					"pageSize": {
						"type": "integer",
						"minimum": 1,
						"maximum": 50
					}
				}
			},
			"CompanySearchResponse": {
				"type": "object",
				"properties": {
					"companies": {
						"type": "array",
						"items": {
							"type": "object",
							"additionalProperties": true
						}
					},
					"page": {
						"type": "integer"
					},
					"pageSize": {
						"type": "integer"
					},
					"total": {
						"type": "integer"
					},
					"totalPages": {
						"type": "integer"
					}
				}
			}
		}
	}
}