{"openapi":"3.1.0","info":{"title":"Tech Companies Portugal API","version":"1.0.0","description":"API for discovering technology companies operating in Portugal.\nEvery data endpoint requires authentication.\n\n[← Back to Tech Companies Portugal](/integrations/api)"},"tags":[{"name":"Companies","description":"Company discovery"},{"name":"Categories","description":"Supported categories"},{"name":"Locations","description":"Supported locations"}],"security":[{"bearerAuth":[]}],"servers":[{"url":"https://techcompaniesportugal.fyi/api/v1"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"TCP API key","description":"Pass your API key as `Authorization: Bearer tcp_live_…`."}},"schemas":{"CompaniesResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Company"}},"meta":{"type":"object","properties":{"total":{"type":"integer","minimum":0,"example":362,"description":"Companies matching the filters, across all pages."},"nextCursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page; null on the last page."},"updatedAt":{"type":"string","format":"date-time","description":"When the directory data last changed."}},"required":["total","nextCursor"]}},"required":["data","meta"]},"Company":{"type":"object","properties":{"slug":{"type":"string","example":"acme"},"name":{"type":"string","example":"Acme"},"description":{"type":"string"},"websiteUrl":{"type":"string","format":"uri"},"careersUrl":{"type":"string","format":"uri"},"githubUrl":{"type":"string","format":"uri"},"instagramUrl":{"type":"string","format":"uri"},"facebookUrl":{"type":"string","format":"uri"},"categories":{"type":"array","items":{"$ref":"#/components/schemas/CategoryReference"}},"locations":{"type":"array","items":{"$ref":"#/components/schemas/LocationReference"}}},"required":["slug","name","description","categories","locations"]},"CategoryReference":{"type":"object","properties":{"slug":{"type":"string","example":"fintech"},"name":{"type":"string","example":"FinTech"}},"required":["slug","name"]},"LocationReference":{"type":"object","properties":{"slug":{"type":"string","example":"lisboa"},"name":{"type":"string","example":"Lisboa"}},"required":["slug","name"]},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","example":"validation_error"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/ErrorDetail"}}},"required":["code","message"]}},"required":["error"]},"ErrorDetail":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"path":{"type":"string"}},"required":["code","message","path"]},"CompanyResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Company"}},"required":["data"]},"CategoriesResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Category"}}},"required":["data"]},"Category":{"allOf":[{"$ref":"#/components/schemas/CategoryReference"},{"type":"object","properties":{"companyCount":{"type":"integer","minimum":0,"example":85}},"required":["companyCount"]}]},"LocationsResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Location"}}},"required":["data"]},"Location":{"allOf":[{"$ref":"#/components/schemas/LocationReference"},{"type":"object","properties":{"companyCount":{"type":"integer","minimum":0,"example":85}},"required":["companyCount"]}]}},"parameters":{}},"paths":{"/companies":{"get":{"operationId":"listCompanies","summary":"List companies","description":"Returns matching companies in slug order, one page at a time. Narrow the list with exact category and location filters, and follow `meta.nextCursor` until it is null.","tags":["Companies"],"parameters":[{"schema":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","example":"fintech"},"required":false,"name":"category","in":"query"},{"schema":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","example":"lisboa"},"required":false,"name":"location","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":100,"description":"Companies per page."},"required":false,"description":"Companies per page.","name":"limit","in":"query"},{"schema":{"type":"string","maxLength":400,"description":"`meta.nextCursor` from the previous page. Opaque."},"required":false,"description":"`meta.nextCursor` from the previous page. Opaque.","name":"cursor","in":"query"}],"responses":{"200":{"description":"A page of companies","headers":{"ETag":{"schema":{"type":"string","description":"Version of this response. Send it back as `If-None-Match` to get an empty 304 while it is unchanged.","example":"\"a1b2c3d4\""},"required":true,"description":"Version of this response. Send it back as `If-None-Match` to get an empty 304 while it is unchanged."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompaniesResponse"}}}},"304":{"description":"Not modified: the `If-None-Match` header matches the current `ETag`. Empty body; reuse the cached response."},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Service temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/companies/{slug}":{"get":{"operationId":"getCompany","summary":"Get a company","tags":["Companies"],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","example":"acme"},"required":true,"name":"slug","in":"path"}],"responses":{"200":{"description":"Company details","headers":{"ETag":{"schema":{"type":"string","description":"Version of this response. Send it back as `If-None-Match` to get an empty 304 while it is unchanged.","example":"\"a1b2c3d4\""},"required":true,"description":"Version of this response. Send it back as `If-None-Match` to get an empty 304 while it is unchanged."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyResponse"}}}},"304":{"description":"Not modified: the `If-None-Match` header matches the current `ETag`. Empty body; reuse the cached response."},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Company not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Service temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/categories":{"get":{"operationId":"listCategories","summary":"List categories","description":"Lists every supported category slug and its company count.","tags":["Categories"],"responses":{"200":{"description":"Available categories","headers":{"ETag":{"schema":{"type":"string","description":"Version of this response. Send it back as `If-None-Match` to get an empty 304 while it is unchanged.","example":"\"a1b2c3d4\""},"required":true,"description":"Version of this response. Send it back as `If-None-Match` to get an empty 304 while it is unchanged."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CategoriesResponse"}}}},"304":{"description":"Not modified: the `If-None-Match` header matches the current `ETag`. Empty body; reuse the cached response."},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Service temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/locations":{"get":{"operationId":"listLocations","summary":"List locations","description":"Lists every supported location slug and its company count.","tags":["Locations"],"responses":{"200":{"description":"Available locations","headers":{"ETag":{"schema":{"type":"string","description":"Version of this response. Send it back as `If-None-Match` to get an empty 304 while it is unchanged.","example":"\"a1b2c3d4\""},"required":true,"description":"Version of this response. Send it back as `If-None-Match` to get an empty 304 while it is unchanged."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocationsResponse"}}}},"304":{"description":"Not modified: the `If-None-Match` header matches the current `ETag`. Empty body; reuse the cached response."},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Service temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"webhooks":{}}