AI Endpoints

The AI API lets you trigger RAMSdoc’s AI features programmatically. All AI endpoints consume credits from your organisation’s allowance.

Generate a document

POST /api/v1/ai/generate-document

Generate a complete RAMS document from a work description.

Request body:

{
  "project_id": "...",
  "site_id": "...",
  "document_type": "rams",
  "work_description": {
    "industry": "electrical",
    "work_type": "Cable tray installation",
    "site_type": "indoor",
    "duration": "2 weeks",
    "working_hours": "08:00-17:00 Monday to Friday",
    "worker_count": 4,
    "equipment": ["MEWP", "cable cutters", "drill", "hand tools"],
    "proximity_to_public": false
  }
}

Response:

Returns the generated document ID. The document is created in draft status.

{
  "data": {
    "document_id": "...",
    "status": "draft",
    "credits_used": 5
  }
}

Cost: 5 credits.

Identify hazards

POST /api/v1/ai/identify-hazards

Analyse a document and suggest missing hazards.

{
  "document_id": "..."
}

Response:

{
  "data": {
    "suggestions": [
      {
        "name": "Noise exposure from drilling",
        "category": "noise",
        "confidence": "high",
        "description": "Workers exposed to noise levels above 85dB(A) during cable tray fixing.",
        "suggested_severity": 3,
        "suggested_likelihood": 4,
        "suggested_controls": [
          {
            "description": "Use low-noise fixings (expansion anchors) where possible",
            "hierarchy_level": "substitution"
          },
          {
            "description": "Ear defenders to EN 352-1 providing minimum SNR 25dB",
            "hierarchy_level": "ppe"
          }
        ]
      }
    ],
    "credits_used": 2
  }
}

Cost: 2 credits.

Generate COSHH assessment

POST /api/v1/ai/generate-coshh

{
  "document_id": "...",
  "substance_name": "Two-pack epoxy resin"
}

Cost: 2 credits.

Generate toolbox talk

POST /api/v1/ai/generate-toolbox-talk

{
  "document_id": "..."
}

Generates a simplified briefing from an approved RAMS. Returns a new linked document ID.

Cost: 2 credits.

Compliance check

POST /api/v1/ai/compliance-check

{
  "document_id": "..."
}

Response:

{
  "data": {
    "score": 82,
    "strengths": ["Good coverage of work at height controls", "..."],
    "gaps": [
      {
        "severity": "critical",
        "description": "No rescue plan for confined space entry at manhole MH-07",
        "regulation": "Confined Spaces Regulations 1997, reg 5"
      }
    ],
    "recommendations": ["Add rescue plan for confined space entry", "..."],
    "credits_used": 3
  }
}

Cost: 3 credits.

Refine a section

POST /api/v1/ai/refine-section

{
  "document_id": "...",
  "section_id": "...",
  "instruction": "Add more detail about cable management and segregation of power and data cables."
}

Cost: 1 credit.

What-if analysis

POST /api/v1/ai/what-if

{
  "document_id": "...",
  "scenario": "What if we need to do this work at night?"
}

Cost: 2 credits.

Translate

POST /api/v1/ai/translate

{
  "document_id": "...",
  "target_language": "pl"
}

Supported language codes: pl (Polish), ro (Romanian), pt (Portuguese), bg (Bulgarian), lt (Lithuanian), hi (Hindi), ur (Urdu), pa (Punjabi), bn (Bengali), es (Spanish), it (Italian).

Cost: 1 credit.

Analyse site photo

POST /api/v1/ai/analyse-photo

Upload a site photo for AI vision analysis. Use multipart/form-data:

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     -F "photo=@site-photo.jpg" \
     -F "document_id=DOCUMENT_ID" \
     "https://api.ramsdoc.com/api/v1/ai/analyse-photo"

Detect interface risks

POST /api/v1/ai/detect-interface-risks

{
  "project_id": "..."
}

Scans all approved RAMS for a project and returns potential interface risks between contractors.

Generate investigation pack

POST /api/v1/ai/generate-investigation-pack

{
  "document_id": "..."
}

Compiles a complete HSE investigation pack as a PDF. Free — no credits consumed.

Error handling

AI endpoints may return specific errors:

Error code	Meaning
`insufficient_credits`	Your organisation does not have enough credits for this action
`document_not_found`	The specified document does not exist or you do not have access
`document_not_approved`	Some actions (e.g. toolbox talk generation) require an approved document
`ai_generation_failed`	The AI generation failed — retry or contact support