Reference REST API - osama1998H/Moca GitHub Wiki

REST API Reference

Full endpoint specification, request/response formats, error codes, and rate limiting.

Base URL

http://{host}:{port}/api/v1

Headers

Header	Required	Description
`X-Moca-Site`	Yes	Target site name
`Content-Type`	For POST/PUT	`application/json`
`Authorization`	If authenticated	`Bearer {token}` or `token {api_key}:{api_secret}`

Interactive API Docs

Method	Endpoint	Purpose
`GET`	`/api/v1/openapi.json`	Generate the OpenAPI 3.0.3 spec as JSON
`GET`	`/api/docs`	Open Swagger UI for the current API version

Operational notes:

include X-Moca-Site when you want the generated spec to include the current site's DocTypes
Swagger UI loads /api/v1/openapi.json from the same origin

Document CRUD

Method	Endpoint	Description
GET	/api/v1/resource/{doctype}	List documents of a given DocType
POST	/api/v1/resource/{doctype}	Create a new document
GET	/api/v1/resource/{doctype}/{name}	Fetch a single document
PUT	/api/v1/resource/{doctype}/{name}	Update a document
DELETE	/api/v1/resource/{doctype}/{name}	Delete a document
GET	/api/v1/resource/{doctype}/{name}/versions	List document versions
GET	/api/v1/meta/{doctype}	Fetch DocType metadata (schema)

Authentication

Method	Endpoint	Description
POST	/api/v1/auth/login	Authenticate with email and password
POST	/api/v1/auth/refresh	Refresh an access token
POST	/api/v1/auth/logout	Invalidate the current session

SSO / OAuth2 / SAML

Method	Endpoint	Description
GET	/api/v1/auth/oauth2/authorize	Initiate OAuth2 authorization flow
GET	/api/v1/auth/oauth2/callback	OAuth2 authorization code callback
GET	/api/v1/auth/saml/metadata	SAML Service Provider metadata (XML)
POST	/api/v1/auth/saml/acs	SAML Assertion Consumer Service endpoint

Workflow

Method	Endpoint	Description
POST	/api/v1/workflow/{doctype}/{name}/transition	Trigger a workflow state transition
GET	/api/v1/workflow/{doctype}/{name}/state	Get current workflow state
GET	/api/v1/workflow/{doctype}/{name}/history	List workflow transition history
GET	/api/v1/workflow/{doctype}/pending	List documents pending a workflow action

Notifications

Method	Endpoint	Description
GET	/api/v1/notifications	List notifications for the current user
GET	/api/v1/notifications/count	Count unread notifications
POST	/api/v1/notifications/mark-read	Mark one or more notifications as read

Search

Method	Endpoint	Description
GET	/api/v1/search	Full-text search across all DocTypes
GET	/api/v1/search/{doctype}	Full-text search within a specific DocType

File Upload

Method	Endpoint	Description
POST	/api/v1/files/upload	Upload a file attachment
GET	/api/v1/files/{file_id}/download	Download an uploaded file

Reports & Dashboards

Method	Endpoint	Description
GET	/api/v1/reports	List available reports
GET	/api/v1/reports/{report_name}	Fetch report metadata
POST	/api/v1/reports/{report_name}/run	Execute a report with parameters
GET	/api/v1/dashboards	List available dashboards
GET	/api/v1/dashboards/{dashboard_name}	Fetch a dashboard definition

GraphQL

Method	Endpoint	Description
POST	/api/graphql	Execute a GraphQL query or mutation
GET	/api/graphql	GraphQL introspection (GET)

Server Method Calls

Method	Endpoint	Description
POST	/api/method/{dotted.path}	Invoke a whitelisted server-side method
GET	/api/method/{dotted.path}	Invoke a whitelisted server-side method (GET)

Custom Endpoints

Method	Endpoint	Description
ANY	/api/v1/custom/{endpoint}	App-defined custom REST endpoint

OpenAPI & Docs

Method	Endpoint	Description
GET	/api/openapi.json	OpenAPI 3.0 specification (JSON)
GET	/api/docs	Interactive Swagger UI documentation

Health & Metrics

Method	Endpoint	Description
GET	/health	Aggregate health check (all subsystems)
GET	/health/ready	Readiness probe (DB + Redis reachable)
GET	/health/live	Liveness probe (process alive)
GET	/metrics	Prometheus metrics endpoint

Rate Limiting

All API endpoints are subject to rate limiting. Limits are applied per tenant and per user.

When a request exceeds the configured limit the server responds with HTTP 429 Too Many Requests.

The following headers are included in every API response:

X-RateLimit-Limit:     1000
X-RateLimit-Remaining: 42
X-RateLimit-Reset:     1712000000
Retry-After:           30