{
 "openapi": "3.1.0",
 "info": {
  "title": "ReLoop.me Role Intel API",
  "version": "1.1.4",
  "summary": "Capability intelligence for job ads.",
  "description": "Send a job ad, get a structured Role-Demand Brief: true seniority, capability mix with evidence, operating style (up to 10 axes), requirement inflation, engagement type and AI exposure. Reads roles, never people: outputs may not be used to rank, screen or reject candidates (Fair Read Charter, https://www.reloop.me/charter). Free, no-key Role Quick Check in about 10 seconds at /role-intel/v1/quick. Full reads take 5-8 minutes: submit, then poll the poll_url or pass a callback_url. Free sandbox key at https://api.reloop.me/#get-a-key. Pricing: full read EUR 3 from a prepaid balance; final price, no VAT added. Pay: the API gives no salary ranges; estimated pay ranges are part of the full Role Intel report, for a limited set of markets. Name: ReLoop.me (always with .me). Full-read data is kept 6 months.",
  "contact": {
   "name": "ReLoop.me",
   "email": "hello@reloop.me",
   "url": "https://api.reloop.me/"
  },
  "termsOfService": "https://www.reloop.me/terms",
  "x-logo": {
   "url": "https://www.reloop.me/favicon.ico"
  }
 },
 "servers": [
  {
   "url": "https://api.reloop.me"
  }
 ],
 "security": [
  {
   "ReLoopKey": []
  }
 ],
 "paths": {
  "/role-intel/v1/reads": {
   "post": {
    "operationId": "createRead",
    "summary": "Submit a job ad for a read",
    "tags": [
     "Reads"
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/ReadRequest"
       }
      }
     }
    },
    "responses": {
     "202": {
      "description": "Accepted; poll poll_url",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ReadAccepted"
        }
       }
      }
     },
     "401": {
      "$ref": "#/components/responses/Error"
     },
     "402": {
      "$ref": "#/components/responses/Error"
     },
     "413": {
      "$ref": "#/components/responses/Error"
     },
     "422": {
      "$ref": "#/components/responses/Error"
     },
     "429": {
      "$ref": "#/components/responses/Error"
     }
    }
   },
   "get": {
    "operationId": "getRead",
    "summary": "Get a read by read_id",
    "tags": [
     "Reads"
    ],
    "parameters": [
     {
      "name": "read_id",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string",
       "pattern": "^rr_[A-Za-z0-9_]+$"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "The read (status processing, delivered, held or failed)",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Read"
        }
       }
      }
     },
     "401": {
      "$ref": "#/components/responses/Error"
     },
     "404": {
      "$ref": "#/components/responses/Error"
     }
    }
   }
  },
  "/health": {
   "get": {
    "operationId": "health",
    "summary": "Service status",
    "security": [],
    "responses": {
     "200": {
      "description": "OK"
     }
    }
   }
  },
  "/role-intel/v1/quick": {
   "post": {
    "operationId": "quickCheck",
    "summary": "Role Quick Check: free, no key, about 10 seconds",
    "description": "Schema role-quick-check/1.1: an indicative level on the ReLoop.me ladder (with track and confidence), title vs scope, scope signals, requirement inflation (codes and short notes), whether pay is disclosed (never a pay figure), core capabilities and the shape of the role on 5 operating-style axes. Includes not_for_you_if and an embeddable Read by ReLoop.me block (lines, text, html) for job pages. Employer never named in the text. Limits: 5 per visitor and 50 in total per day. The ad text is not stored.",
    "tags": [
     "Quick"
    ],
    "security": [],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "jd_text"
        ],
        "properties": {
         "jd_text": {
          "type": "string",
          "minLength": 300,
          "maxLength": 15000
         },
         "location": {
          "type": "string"
         },
         "source": {
          "type": "string",
          "description": "Where you found ReLoop.me (optional)"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Quick read",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/QuickRead"
        }
       }
      }
     },
     "413": {
      "$ref": "#/components/responses/Error"
     },
     "422": {
      "$ref": "#/components/responses/Error"
     },
     "429": {
      "$ref": "#/components/responses/Error"
     },
     "502": {
      "$ref": "#/components/responses/Error"
     }
    }
   }
  }
 },
 "components": {
  "securitySchemes": {
   "ReLoopKey": {
    "type": "apiKey",
    "in": "header",
    "name": "x-reloop-key",
    "description": "rl_sandbox_... (sample reads, free) or rl_live_... (billed per delivered full read). Not needed for /role-intel/v1/quick."
   }
  },
  "responses": {
   "Error": {
    "description": "Error",
    "content": {
     "application/json": {
      "schema": {
       "type": "object",
       "properties": {
        "error": {
         "type": "object",
         "properties": {
          "code": {
           "type": "string"
          },
          "message": {
           "type": "string"
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "schemas": {
   "ReadRequest": {
    "type": "object",
    "required": [
     "jd_text"
    ],
    "properties": {
     "jd_text": {
      "type": "string",
      "minLength": 200,
      "maxLength": 20000,
      "description": "Full job ad text. Emails and phone numbers are removed before storage."
     },
     "location": {
      "type": "string",
      "description": "City or country, if known."
     },
     "client_ref": {
      "type": "string",
      "description": "Your own reference, returned with the read."
     },
     "callback_url": {
      "type": "string",
      "format": "uri",
      "description": "https URL; we POST {read_id,status} when done."
     }
    }
   },
   "ReadAccepted": {
    "type": "object",
    "properties": {
     "read_id": {
      "type": "string"
     },
     "status": {
      "type": "string",
      "enum": [
       "processing",
       "queued"
      ]
     },
     "poll_url": {
      "type": "string",
      "format": "uri"
     },
     "rdb_version": {
      "type": "string"
     },
     "review_required": {
      "type": "boolean"
     },
     "sandbox": {
      "type": "boolean"
     }
    }
   },
   "Read": {
    "type": "object",
    "properties": {
     "read_id": {
      "type": "string"
     },
     "status": {
      "type": "string",
      "enum": [
       "processing",
       "delivered",
       "held",
       "failed"
      ]
     },
     "held_reason": {
      "type": "string"
     },
     "engine": {
      "type": "object"
     },
     "pay_status": {
      "type": "string",
      "description": "Always 'not_in_api'."
     },
     "tiers_delivered": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "rdb": {
      "$ref": "#/components/schemas/RoleDemandBrief"
     },
     "attribution": {
      "type": "object"
     }
    }
   },
   "RoleDemandBrief": {
    "type": "object",
    "description": "Role-Demand Brief (RDB 0.1.3). Null means not measured, never zero.",
    "properties": {
     "rdb_version": {
      "type": "string"
     },
     "role_title_stated": {
      "type": "string"
     },
     "true_seniority": {
      "type": "object",
      "properties": {
       "level": {
        "type": "string",
        "enum": [
         "Emerging",
         "Demonstrated",
         "Expert",
         "Distinctive",
         "Manager",
         "Senior Manager",
         "Director",
         "Head of Function",
         "VP",
         "Executive"
        ]
       },
       "track": {
        "type": "string"
       },
       "title_stated_gap": {
        "type": "string"
       },
       "rationale": {
        "type": "string"
       }
      }
     },
     "scope": {
      "type": "object"
     },
     "capability_mix": {
      "type": "array",
      "items": {
       "type": "object",
       "properties": {
        "capability": {
         "type": "string"
        },
        "weight": {
         "type": "string",
         "enum": [
          "primary",
          "secondary",
          "supporting"
         ]
        },
        "level": {
         "type": "string"
        },
        "evidence": {
         "type": "string"
        }
       }
      }
     },
     "jd_inflation_index": {
      "type": "object",
      "properties": {
       "rating": {
        "type": "string",
        "enum": [
         "none",
         "low",
         "medium",
         "high"
        ]
       },
       "signals": {
        "type": "array",
        "items": {
         "type": "string"
        }
       },
       "supported_level": {
        "type": "string"
       }
      }
     },
     "engagement_type": {
      "type": "string"
     },
     "operating_style": {
      "type": "object",
      "properties": {
       "scale": {
        "type": "string"
       },
       "axes": {
        "type": "array",
        "items": {
         "type": "object",
         "properties": {
          "axis_id": {
           "type": "string"
          },
          "kind": {
           "type": "string",
           "enum": [
            "operating_style",
            "ad_signal"
           ]
          },
          "low_end": {
           "type": "string"
          },
          "high_end": {
           "type": "string"
          },
          "position": {
           "type": "number",
           "minimum": -1,
           "maximum": 1
          },
          "label": {
           "type": "string"
          }
         }
        }
       },
       "reading_rule": {
        "type": "string"
       }
      }
     },
     "ai_exposure": {
      "type": "object"
     },
     "operating_stage": {
      "type": "string"
     },
     "market": {
      "type": "object"
     },
     "pay_status": {
      "type": "string",
      "description": "Always 'not_in_api': the API gives no salary ranges."
     },
     "links": {
      "type": "object"
     },
     "full_read_includes": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "reading_rules": {
      "type": "object",
      "description": "Fair Read Charter rules that travel with the data. Keep them with the data."
     },
     "attribution": {
      "type": "string"
     },
     "attribution_url": {
      "type": "string"
     }
    }
   },
   "QuickRead": {
    "type": "object",
    "description": "role-quick-check/1.1. Null means not measured, never zero.",
    "properties": {
     "ok": {
      "type": "boolean"
     },
     "quick_id": {
      "type": "string"
     },
     "schema": {
      "type": "string"
     },
     "product": {
      "type": "string"
     },
     "language": {
      "type": "string"
     },
     "role": {
      "type": "object",
      "properties": {
       "title": {
        "type": [
         "string",
         "null"
        ]
       },
       "family": {
        "type": [
         "string",
         "null"
        ],
        "enum": [
         "engineering",
         "data_ai",
         "product",
         "design",
         "marketing",
         "sales",
         "customer_success",
         "operations",
         "finance",
         "hr_people",
         "legal_compliance",
         "executive_leadership",
         "nonprofit_public",
         "other",
         null
        ]
       },
       "engagement_type": {
        "type": [
         "string",
         "null"
        ],
        "enum": [
         "employment",
         "contract",
         "fractional",
         "freelance",
         "internship",
         "board",
         "unclear",
         null
        ]
       },
       "work_mode": {
        "type": [
         "string",
         "null"
        ],
        "enum": [
         "remote",
         "hybrid",
         "onsite",
         "unclear",
         null
        ]
       }
      }
     },
     "level": {
      "type": "object",
      "properties": {
       "rung": {
        "type": [
         "string",
         "null"
        ],
        "enum": [
         "Emerging",
         "Demonstrated",
         "Expert",
         "Distinctive",
         "Manager",
         "Senior Manager",
         "Director",
         "Head of Function",
         "VP",
         "Executive",
         null
        ]
       },
       "track": {
        "type": [
         "string",
         "null"
        ],
        "enum": [
         "individual_contributor",
         "people_manager",
         "executive",
         null
        ]
       },
       "confidence": {
        "type": [
         "string",
         "null"
        ],
        "enum": [
         "low",
         "medium",
         "high",
         null
        ]
       },
       "basis": {
        "type": [
         "string",
         "null"
        ]
       },
       "indicative": {
        "type": "boolean"
       }
      }
     },
     "title_vs_scope": {
      "type": "object",
      "properties": {
       "verdict": {
        "type": [
         "string",
         "null"
        ],
        "enum": [
         "aligned",
         "title_higher",
         "title_lower",
         "unclear",
         null
        ]
       },
       "note": {
        "type": [
         "string",
         "null"
        ]
       }
      }
     },
     "scope_signals": {
      "type": "array",
      "items": {
       "type": "string",
       "enum": [
        "owns_function",
        "owns_product_area",
        "sets_strategy",
        "executes_defined_scope",
        "manages_people",
        "manages_managers",
        "reports_to_executive",
        "reports_to_board",
        "budget_owner",
        "cross_functional_lead",
        "client_facing",
        "builds_from_zero",
        "scales_existing",
        "hands_on_delivery",
        "no_team_named"
       ]
      }
     },
     "inflation": {
      "type": "object",
      "properties": {
       "level": {
        "type": [
         "string",
         "null"
        ],
        "enum": [
         "none",
         "low",
         "medium",
         "high",
         null
        ]
       },
       "codes": {
        "type": "array",
        "items": {
         "type": "string",
         "enum": [
          "years_above_scope",
          "unicorn_skill_stack",
          "seniority_above_scope",
          "title_above_scope",
          "unrelated_mandates",
          "excessive_must_haves",
          "vague_requirements"
         ]
        }
       },
       "notes": {
        "type": "array",
        "items": {
         "type": "string"
        }
       }
      }
     },
     "pay": {
      "type": "object",
      "properties": {
       "disclosed": {
        "type": [
         "string",
         "null"
        ],
        "enum": [
         "yes",
         "partial",
         "no",
         null
        ]
       },
       "note": {
        "type": [
         "string",
         "null"
        ]
       },
       "salary_range_included": {
        "type": "boolean",
        "const": false
       }
      }
     },
     "capabilities": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "bigger_picture": {
      "type": [
       "string",
       "null"
      ]
     },
     "operating_style": {
      "type": "object",
      "properties": {
       "scale": {
        "type": "string"
       },
       "axes": {
        "type": "array",
        "items": {
         "type": "object",
         "properties": {
          "axis_id": {
           "type": "string",
           "enum": [
            "execution_strategy",
            "maintain_build",
            "specialist_generalist",
            "ic_manager",
            "clear_ambiguous_scope"
           ]
          },
          "low_end": {
           "type": "string"
          },
          "high_end": {
           "type": "string"
          },
          "position": {
           "type": "number",
           "minimum": -1,
           "maximum": 1
          },
          "why": {
           "type": [
            "string",
            "null"
           ]
          }
         }
        }
       },
       "reading_rule": {
        "type": "string"
       }
      }
     },
     "display": {
      "type": "object",
      "properties": {
       "headline": {
        "type": "string"
       },
       "badges": {
        "type": "array",
        "items": {
         "type": "object",
         "properties": {
          "key": {
           "type": "string"
          },
          "value": {
           "type": "string"
          },
          "label": {
           "type": "string"
          }
         }
        }
       }
      }
     },
     "not_included": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "next": {
      "type": "object"
     },
     "reading_rules": {
      "type": "object"
     },
     "attribution": {
      "type": "object"
     },
     "disclaimer": {
      "type": "string"
     },
     "not_for_you_if": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "1-2 statements about how the role is set up (never about a person or protected traits)."
     },
     "embed": {
      "type": "object",
      "description": "'Read by ReLoop.me' block for a job page. Keep the attribution link.",
      "properties": {
       "title": {
        "type": "string"
       },
       "lines": {
        "type": "array",
        "items": {
         "type": "object",
         "properties": {
          "key": {
           "type": "string"
          },
          "label": {
           "type": "string"
          },
          "value": {
           "type": "string"
          }
         }
        }
       },
       "text": {
        "type": "string"
       },
       "html": {
        "type": "string"
       },
       "attribution_required": {
        "type": "boolean"
       }
      }
     }
    }
   }
  }
 },
 "tags": [
  {
   "name": "Quick",
   "description": "Free, instant role quick check"
  },
  {
   "name": "Reads",
   "description": "Role Intel reads of job ads"
  }
 ],
 "externalDocs": {
  "url": "https://api.reloop.me/",
  "description": "Quickstart and reading rules"
 }
}