Try Me!

Summary

Returns a list of all companies whose data is currently present in the database.

This endpoint is designed for read-only access and is commonly used by client applications to populate selectors such as dropdowns, filters, and search facets.

Description

The Fetch Companies API retrieves companies records from the database and returns them as a JSON array.

Key characteristics of this endpoint:

• Publicly accessible (no authentication required)
• No query parameters or request body
• Database identifiers (_id) are excluded from responses
• Empty results are treated as a valid, non-error response
• Clear separation between database errors and unexpected server failures

This endpoint serves as the authoritative source of company data across the platform.

Endpoint

GET /api/companies

Request

This endpoint does not accept any parameters

Headers

This endpoint does not accept any parameters

Response Schema

Success - 200 OK

Company[]

Company Object

Example Response

[
  {
    "name": "Apple",
    "slug": "apple",
    "country": "North America",
    "industry": "Technology"
  },
  {
    "name": "BHP",
    "slug": "bhp",
    "country": "Australia",
    "industry": "Mining"
  }
]

Empty Response

If no companies are available, an empty array is returned:

[]

Error Codes & Response Types

503 Service Unavailable

Returned when the database is temporarily unavailable, or a query fails due to a database issue

Response Body

{
    "detail" : "Database temporarily unavailable"
}

Typical Causes

1. MongoDB Connection Issues
2. Database timeout or query failure for a non-general reason

500 Internal Server Error

Returned when an unexpected server-side error occurs.

Response Body

{
    "detail" : "Internal server error"
}

Typical Causes

1. Unhandled runtime exception
2. Application-level failure outside database operations.

Implementation Notes

1. Uses a MongoDB find() query with projection to exclude _id
2. Materializes the cursor before returning the response
3. Logs both database-specific and unexpected errors for observability
4. Treats empty datasets as a valid state, not an error condition