API Overview

The Serko Northsky API is a RESTful API built with FastAPI, providing endpoints for travel management operations.

Base URL

Environment	URL
Local	http://localhost:8000
Development	https://api.dev.serko-northsky.com
Production	https://api.serko-northsky.com

API Documentation

The API is documented using OpenAPI (Swagger). Access the interactive documentation:

• Swagger UI: /docs
• ReDoc: /redoc
• OpenAPI JSON: /openapi.json

API Structure

/api
├── /companies          # Company management
├── /conversations      # AI conversation history
├── /hotels             # Hotel search results
├── /loyalty-programs   # Loyalty program memberships
├── /policy             # Company travel policies
├── /users              # User profile management
└── /database           # Database utilities (dev only)

Request Format

Headers

All requests should include:

Content-Type: application/json
Authorization: Bearer {firebase_id_token}

Request Body

POST and PATCH requests use JSON:

{
  "field_name": "value",
  "nested": {
    "field": "value"
  }
}

Response Format

Success Response

{
  "id": "uuid",
  "created_at": "2025-01-15T10:30:00Z",
  "field": "value"
}

Error Response

{
  "detail": "Error message",
  "errors": [
    {
      "loc": ["body", "field_name"],
      "msg": "Field is required",
      "type": "value_error.missing"
    }
  ]
}

HTTP Status Codes

Code	Meaning
200	Success
201	Created
204	No Content
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
422	Validation Error
429	Rate Limited
500	Internal Server Error

Common Endpoints

Users

Method	Endpoint	Description
GET	/api/users/profile	Get current user profile
PATCH	/api/users/profile	Update user profile
GET	/api/users/preferences	Get user preferences
PUT	/api/users/preferences	Update preferences

Companies

Method	Endpoint	Description
POST	/api/companies	Create company
GET	/api/companies/{id}	Get company details
PATCH	/api/companies/{id}	Update company

Policies

Method	Endpoint	Description
POST	/api/policy	Create policy
GET	/api/policy/{id}	Get policy with rules
PATCH	/api/policy/{id}	Update policy

Hotels

Method	Endpoint	Description
GET	/api/hotels/rubric/{id}	Get hotels by rubric

Loyalty Programs

Method	Endpoint	Description
GET	/api/loyalty-programs	List all programs
GET	/api/loyalty-programs/user	Get user memberships
POST	/api/loyalty-programs/user	Add membership

AI Agent Integration

The backend integrates AI agents through the conversation endpoint. AI tools are implemented using PydanticAI agents rather than direct API endpoints.

See AI Orchestration for details on the agent system.

Agent Tools

Tool	Agent	Description
search_accommodations	Trip Planner	Search hotels via Booking.com + Sabre
search_flights	Trip Planner	Search flights via QPX Connect
get_search_results	Trip Planner	Retrieve ranked results
recommend_options	Trip Planner	Select top recommendations
create_trip_step	Context	Add flight/accommodation step
add_preference	Context	Add trip-specific preference

Rate Limiting

API endpoints are rate-limited:

Tier	Requests/Minute
Free	60
Standard	300
Enterprise	1000

Rate limit headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1642687200

Pagination

List endpoints support pagination:

GET /api/hotels/rubric/{id}?page=1&page_size=20

Response includes pagination metadata:

{
  "items": [...],
  "total": 100,
  "page": 1,
  "page_size": 20,
  "pages": 5
}

Related Documentation

• Authentication — Auth flow details
• Backend Architecture — Technical architecture