Introduction

The Oche API is a RESTful JSON API that powers the mobile app and can be used for third-party integrations. All responses are in JSON format.

Detail	Value
Base URL	https://oche.tekninja.uk/api
Format	JSON
Auth	Bearer token (Laravel Sanctum)

Authentication

Most API endpoints require authentication. Oche uses Laravel Sanctum bearer tokens.

Register

POST /api/auth/register

{
  "name": "John Smith",
  "email": "john@example.com",
  "password": "your-password",
  "password_confirmation": "your-password"
}

Login

POST /api/auth/login

{
  "email": "john@example.com",
  "password": "your-password"
}

Response:
{
  "token": "1|abc123...",
  "user": { "id": 1, "name": "John Smith", ... }
}

Using the Token

Include the token in the Authorization header for all authenticated requests:

Authorization: Bearer 1|abc123...

Device Authentication

For guest mode (no account), devices authenticate via a unique device ID:

POST /api/auth/device

{
  "device_id": "unique-device-uuid"
}

Endpoints Overview

Health Check

Method	Endpoint	Auth	Description
GET	/api/ping	No	Server health check

Players

Method	Endpoint	Description
GET	/api/players	List all players
POST	/api/players	Create a player
GET	/api/players/{id}	Get player details
PUT	/api/players/{id}	Update a player
DELETE	/api/players/{id}	Delete a player
GET	/api/players/{id}/stats	Get player statistics

Games

Method	Endpoint	Description
GET	/api/games	List games (paginated)
POST	/api/games	Create a new game
GET	/api/games/{uuid}	Get game details
POST	/api/games/{uuid}/turns	Add a turn/score
DELETE	/api/games/{uuid}/turns/last	Undo last turn
POST	/api/games/sync	Sync offline games

Venues

Method	Endpoint	Description
GET	/api/venues	List venues
POST	/api/venues	Create a venue
GET	/api/venues/{id}	Get venue details
GET	/api/venues/{id}/stats	Venue statistics
POST	/api/venues/{id}/checkin	Check in to venue
POST	/api/venues/{id}/checkout	Check out of venue

Tournaments

Method	Endpoint	Description
GET	/api/tournaments	List tournaments
POST	/api/tournaments	Create a tournament
GET	/api/tournaments/{id}	Get tournament details
POST	/api/tournaments/{id}/start	Start the tournament
POST	/api/tournaments/fixtures/{id}/result	Submit fixture result
GET	/api/tournaments/{id}/stats	Tournament statistics

Error Responses

The API uses standard HTTP status codes:

Code	Meaning
200	Success
201	Created
401	Unauthenticated — invalid or missing token
403	Forbidden — insufficient permissions
404	Not found
422	Validation error — check the errors field
500	Server error

Validation Error Format

{
  "message": "The given data was invalid.",
  "errors": {
    "email": ["The email field is required."],
    "password": ["The password must be at least 8 characters."]
  }
}

Rate Limiting

The API enforces rate limiting to prevent abuse. Current limits:

• 60 requests per minute for authenticated users
• 20 requests per minute for unauthenticated requests

Rate limit headers are included in every response:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58

See Also

• Getting Started — App setup guide
• FAQ — Common questions