Medusa API Reference

Internal API endpoints for Medusa content intake automation system.

Authentication

All API endpoints require authentication via user-token header.

Authorization: Bearer {user-token}

Tokens are managed through Farfalla's authentication system.

---

REST API Endpoints

Base URL: https://medusa.publica.la/api/v1

List Automations

Returns all automations configured for a tenant.

Request

GET /api/v1/automations

Parameters

Parameter	Type	Required	Description
tenant_id	integer	Yes	Tenant identifier

Example Request

curl -X GET "https://medusa.publica.la/api/v1/automations?tenant_id=123" \
  -H "Authorization: Bearer {token}"

Response

{
  "data": [
    {
      "id": 1,
      "name": "Daily Publication",
      "description": "Automated daily content publishing",
      "status": "active"
    }
  ]
}

---

Dispatch Automation

Triggers an automation job manually.

Request

GET /api/v1/dispatch/{automation}

Path Parameters

Parameter	Type	Required	Description
automation	integer	Yes	Automation ID

Query Parameters

Parameter	Type	Required	Description
date	string	No	Target date (YYYY-MM-DD)
action	string	No	Action type: dispatch or redispatch
issue_id	integer	No	Specific issue ID for redispatch
user_id	integer	No	User triggering the automation
user_email	string	No	Email for notifications
process_type	string	No	Processing mode

Example Request

curl -X GET "https://medusa.publica.la/api/v1/dispatch/1?date=2026-01-22&action=dispatch" \
  -H "Authorization: Bearer {token}"

Response

{
  "success": true,
  "message": "Automation dispatched",
  "run_id": 456
}

---

Nova Tool APIs

Administrative APIs accessible through Laravel Nova interface.

Base URL: https://medusa.publica.la/nova-api/tools

ONIX Validator

Validates ONIX XML files against standard specifications.

Request

POST /nova-api/tools/onix-validator/api/

Headers

Header	Value
Content-Type	multipart/form-data

Body

Field	Type	Required	Description
file	file	Yes	ONIX XML file (max 4MB)

Example Request

curl -X POST "https://medusa.publica.la/nova-api/tools/onix-validator/api/" \
  -H "Authorization: Bearer {token}" \
  -F "file=@onix_file.xml"

Response

{
  "valid": true,
  "required_fields": {
    "present": ["RecordReference", "NotificationType", "ProductIdentifier"],
    "missing": []
  },
  "optional_fields": {
    "present": ["Title", "Contributor", "Subject"],
    "missing": ["Audience", "OtherText"]
  },
  "error_count": 0,
  "warnings": []
}

---

ISBN Tracker

Tracks ISBN processing status across the ONIX intake pipeline.

Get ISBN Status

Request

GET /nova-api/tools/isbn-tracker/api/{isbn}

Path Parameters

Parameter	Type	Required	Description
isbn	string	Yes	ISBN-10 or ISBN-13

Example Request

curl -X GET "https://medusa.publica.la/nova-api/tools/isbn-tracker/api/9781234567890" \
  -H "Authorization: Bearer {token}"

Response

{
  "isbn": "9781234567890",
  "current_state": {
    "onix_file": {
      "id": 123,
      "status": "processed",
      "processed_at": "2026-01-22T10:00:00Z"
    },
    "onix_event": {
      "id": 456,
      "status": "completed",
      "event_type": "create"
    },
    "onix_issue": {
      "id": 789,
      "status": "ingested",
      "farfalla_issue_id": 1234
    }
  },
  "previous_states": []
}

---

Force Discover Events

Manually triggers ONIX event discovery for an ISBN.

Request

POST /nova-api/tools/isbn-tracker/api/{isbn}/force-discover-events

Response

{
  "success": true,
  "message": "Event discovery triggered",
  "events_found": 2
}

---

Force Process Event

Manually triggers ONIX event processing.

Request

POST /nova-api/tools/isbn-tracker/api/{isbn}/force-process-event

Response

{
  "success": true,
  "message": "Event processing triggered"
}

---

Force Ingest Issue

Manually triggers issue ingestion to Farfalla.

Request

POST /nova-api/tools/isbn-tracker/api/{isbn}/force-ingest-issue

Response

{
  "success": true,
  "message": "Issue ingestion triggered",
  "farfalla_issue_id": 1234,
  "validation": {
    "has_content": true,
    "has_metadata": true,
    "has_cover": true
  }
}

---

Health Endpoints

Ping

Simple health check.

Request

GET /ping

Response

Pong! 2026-01-22 10:00:00

---

Health Check

Full system health status (requires authentication).

Request

GET /health

Response

{
  "status": "healthy",
  "database": "connected",
  "queue": "running",
  "storage": "accessible"
}

---

Error Responses

All endpoints return consistent error format:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid tenant_id parameter",
    "details": {}
  }
}

Common Error Codes

Code	HTTP Status	Description
UNAUTHORIZED	401	Invalid or missing token
FORBIDDEN	403	Insufficient permissions
NOT_FOUND	404	Resource not found
VALIDATION_ERROR	422	Invalid request parameters
INTERNAL_ERROR	500	Server error

---

Rate Limiting

API requests are rate-limited per tenant:

Endpoint Type	Limit
REST API	100 requests/minute
Nova Tools	20 requests/minute

Exceeded limits return HTTP 429 with Retry-After header.