Middle-earth API

Forge a ring

POST/rings

Forges a new ring of the requested kind and metal. Elven, dwarven and human rings only need a smith and a metal. The One Ring is different: it needs the Dark Lord's approval and a binding inscription.

Handle with care

Once a ring of kind one is forged, it starts corrupting every bearer. There is no undo; see Destroy a ring.

Request

Header parameters

  • Idempotency-Key string

    Any unique string. Reusing one returns the original ring instead of forging a second.

Bodyapplication/json

  • kind string <RingKind> Required

    The kind of ring.

    Allowed valueselvendwarvenhumanone

  • metal string <Metal> Required

    Metal the ring is made from.

    Allowed valuesgoldsilvermithriliron

  • smith_id string Required

    The forging smith.

    Must belong to a smith registered with the guild of the requested kind.

  • gem string

    Optional gem to set into the ring.

  • inscription object <Inscription>

    Required when kind is one

    Text inscribed on the ring.

  • dark_lord_approval string conditional

    Required when kind is one

    Approval token from the Dark Lord.

    Required only when kind is one. Obtain the token from Mount Doom before forging; rings of any other kind ignore this field.

Example request

cURL
curl -X POST 'https://api.middle-earth.example/v3/rings' \
  -H 'Content-Type: application/json' \
  -d '{
  "kind": "elven",
  "metal": "mithril",
  "smith_id": "smith_celebrimbor",
  "gem": "diamond"
}'

Response

Ring forged.

Body

  • id string Required

    Unique identifier.

  • kind string <RingKind> Required

    The kind of ring.

    Allowed valueselvendwarvenhumanone

  • metal string <Metal> Required

    Metal the ring is made from.

    Allowed valuesgoldsilvermithriliron

  • status string Required

    Where the ring is right now.

    Allowed valuesforgedwornlostdestroyed

  • bearer_id string

    null while the ring is unworn or lost.

  • inscription object <Inscription>

    Text inscribed on the ring.

  • corruption_level integer

    A value from 0 to 100 that grows each day a ring is worn. The One Ring starts at 60.

  • forged_at string date-time

    When the ring was forged.

Example response

application/json

Json
{
  "id": "ring_001",
  "kind": "elven",
  "metal": "mithril",
  "status": "forged",
  "bearer_id": null,
  "corruption_level": 0,
  "forged_at": "1590-06-01T10:00:00Z"
}