Metis Events API

Check your credentials

GET/v1/connectionno scope needed

Returns the Metis account your key is acting on and the scopes it was granted. Call it once at start-up, or whenever a new key is entered in your settings, to prove the key works before you try anything else. It needs no scope of its own.

Returns

A connection object.

Example response

{
  "id": "con_8fK2mQpL4xRz9TbW3vNcYh7J",
  "partner": {
    "name": "Our booking system"
  },
  "account": {
    "name": "Your Venues Ltd"
  },
  "scopes": [
    "venues:read",
    "occasions:read",
    "occasions:write",
    "floorplans:read",
    "floorplans:write",
    "links:create"
  ]
}

Notes

• This is the call to use in a 'Test connection' button.

Example request

curl -sS "$METIS_BASE/v1/connection" \
  -H "Authorization: Bearer $METIS_API_KEY" \
  -H "Metis-Connection: $METIS_CONNECTION"

const result = await metis("/v1/connection");
console.log(result);

using var response = await http.GetAsync("v1/connection");
response.EnsureSuccessStatusCode();
var result = await response.Content.ReadFromJsonAsync<JsonElement>();

List venues

GET/v1/venuesscope venues:read

Your venues — the buildings or sites you run events in. Use it to populate a venue picker in your own system. Rooms live underneath a venue.

Query parameters

Returns

A page of venues, each with the number of rooms it has.

Example response

{
  "data": [
    {
      "id": "ven_8",
      "name": "Grand Hotel",
      "roomCount": 6
    }
  ],
  "hasMore": false,
  "nextCursor": null
}

Example request

curl -sS "$METIS_BASE/v1/venues?limit=25" \
  -H "Authorization: Bearer $METIS_API_KEY" \
  -H "Metis-Connection: $METIS_CONNECTION"

const result = await metis("/v1/venues");
console.log(result);

using var response = await http.GetAsync("v1/venues");
response.EnsureSuccessStatusCode();
var result = await response.Content.ReadFromJsonAsync<JsonElement>();

Retrieve a venue

GET/v1/venues/{venueId}scope venues:read

One venue by id. Useful when you store the venue id against your own site record and want to show its current name.

Path parameters

Returns

A venue object.

Example response

{
  "id": "ven_8",
  "name": "Grand Hotel",
  "roomCount": 6
}

Example request

curl -sS "$METIS_BASE/v1/venues/ven_8" \
  -H "Authorization: Bearer $METIS_API_KEY" \
  -H "Metis-Connection: $METIS_CONNECTION"

const result = await metis("/v1/venues/ven_8");
console.log(result);

using var response = await http.GetAsync("v1/venues/ven_8");
response.EnsureSuccessStatusCode();
var result = await response.Content.ReadFromJsonAsync<JsonElement>();

List a venue's rooms

GET/v1/venues/{venueId}/roomsscope venues:read

Every room at a venue, with its dimensions and any layouts already saved for it in Metis. A room is structure only — walls, doors, windows, pillars and fixed features, with no furniture; furniture is laid out per event. This is the call that feeds your room picker, and the room id is what you send when you ask for a plan.

Path parameters

Returns

All of that venue's rooms in a single page.

Example response

{
  "data": [
    {
      "id": "room_26",
      "venueId": "ven_8",
      "name": "Ballroom",
      "structureVersion": 3,
      "dimensions": {
        "widthCm": 1800,
        "lengthCm": 2400,
        "ceilingHeightCm": 420
      },
      "layouts": [
        {
          "id": "lay_58",
          "name": "Cabaret Banquet, Dancefloor & Disco",
          "updatedAt": "2026-08-30T14:02:11Z"
        }
      ]
    }
  ],
  "hasMore": false,
  "nextCursor": null
}

Notes

• structureVersion tells you which published version of the room a plan was built from. It changes whenever the room is re-measured or re-drawn in Metis.
• A version number is not by itself a guarantee of a usable room: versions published before the planner's 2026-09-22 release could be saved with no walls, and a plan request against a wall-less structure succeeds but generates its layout into an empty page. The planner now refuses wall-less publishes, so newer versions always contain walls. If plans for a room come back empty, ask the venue to redraw the room's walls and publish again.

Example request

curl -sS "$METIS_BASE/v1/venues/ven_8/rooms" \
  -H "Authorization: Bearer $METIS_API_KEY" \
  -H "Metis-Connection: $METIS_CONNECTION"

const result = await metis("/v1/venues/ven_8/rooms");
console.log(result);

using var response = await http.GetAsync("v1/venues/ven_8/rooms");
response.EnsureSuccessStatusCode();
var result = await response.Content.ReadFromJsonAsync<JsonElement>();

Retrieve a room

GET/v1/rooms/{roomId}scope venues:read

One room by id, with the same detail as the list above. Handy for refreshing a room you have stored without re-reading the whole venue.

Path parameters

Returns

A room object.

Example response

{
  "id": "room_26",
  "venueId": "ven_8",
  "name": "Ballroom",
  "structureVersion": 3,
  "dimensions": {
    "widthCm": 1800,
    "lengthCm": 2400,
    "ceilingHeightCm": 420
  },
  "layouts": []
}

Example request

curl -sS "$METIS_BASE/v1/rooms/room_26" \
  -H "Authorization: Bearer $METIS_API_KEY" \
  -H "Metis-Connection: $METIS_CONNECTION"

const result = await metis("/v1/rooms/room_26");
console.log(result);

using var response = await http.GetAsync("v1/rooms/room_26");
response.EnsureSuccessStatusCode();
var result = await response.Content.ReadFromJsonAsync<JsonElement>();

List layout styles

GET/v1/layout-stylesscope venues:read

The room layouts Metis can generate — banquet rounds, cabaret, theatre, classroom and so on — with the options each one takes. Every style also accepts the three extras (top table, dance floor, stage) — Metis does not place them, it flags each one to the venue to add by hand. Read this to build your layout picker instead of hard-coding the list, because styles get added.

Returns

Every layout style in one page.

Example response

{
  "data": [
    {
      "key": "banquet",
      "name": "Banquet (round tables)",
      "generatesFurniture": true,
      "options": [
        {
          "name": "tableSize",
          "minimum": 1,
          "maximum": 40,
          "default": 10
        }
      ],
      "extras": [
        "topTable",
        "danceFloor",
        "stage"
      ]
    }
  ],
  "hasMore": false,
  "nextCursor": null
}

Notes

• generatesFurniture: false (e.g. reception) means Metis prepares the room but your team places the furniture by hand.

Example request

curl -sS "$METIS_BASE/v1/layout-styles" \
  -H "Authorization: Bearer $METIS_API_KEY" \
  -H "Metis-Connection: $METIS_CONNECTION"

const result = await metis("/v1/layout-styles");
console.log(result);

using var response = await http.GetAsync("v1/layout-styles");
response.EnsureSuccessStatusCode();
var result = await response.Content.ReadFromJsonAsync<JsonElement>();

List occasions

GET/v1/occasionsscope occasions:read

The events your system has told Metis about, earliest date first. Use it to reconcile after an outage, or to show what Metis already knows.

Query parameters

Returns

A page of occasions ordered by date. Filters are optional and combine.

Example response

{
  "data": [
    {
      "id": "occ_42",
      "name": "Smith-Jones Wedding",
      "date": "2027-06-12",
      "type": "wedding",
      "guestCount": 150,
      "venueId": "ven_8",
      "externalReference": "CRM-10492",
      "createdBy": {
        "name": "Alex Planner",
        "email": "[email protected]"
      },
      "createdAt": "2026-09-17T08:34:06Z",
      "updatedAt": "2026-09-17T08:34:06Z"
    }
  ],
  "hasMore": false,
  "nextCursor": null
}

Example request

curl -sS "$METIS_BASE/v1/occasions?year=2027&limit=25" \
  -H "Authorization: Bearer $METIS_API_KEY" \
  -H "Metis-Connection: $METIS_CONNECTION"

const result = await metis("/v1/occasions");
console.log(result);

using var response = await http.GetAsync("v1/occasions");
response.EnsureSuccessStatusCode();
var result = await response.Content.ReadFromJsonAsync<JsonElement>();

Create an occasion

POST/v1/occasionsscope occasions:write

An occasion is an event — the wedding, conference or dinner the plan will be for. This is normally the first call you make for a booking; everything else (plan requests, floorplans) hangs off the occasion it returns. Put your own booking reference in externalReference so you can find it again.

Headers

Body fields

Returns

201 Created with the occasion, a Location header and an ETag.

Errors worth handling

Notes

• Retrying with the same Idempotency-Key returns the original occasion and the header Idempotent-Replayed: true, so a network timeout never creates a duplicate.

Example request

curl -sS -X POST "$METIS_BASE/v1/occasions" \
  -H "Authorization: Bearer $METIS_API_KEY" \
  -H "Metis-Connection: $METIS_CONNECTION" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name": "Smith-Jones Wedding", "date": "2027-06-12", "type": "wedding", "guestCount": 150, "venueId": "ven_8", "externalReference": "CRM-10492", "createdBy": {"name": "Alex Planner", "email": "[email protected]"}}'

const created = await metis("/v1/occasions", { method: "POST", body: {
    "name": "Smith-Jones Wedding",
    "date": "2027-06-12",
    "type": "wedding",
    "guestCount": 150,
    "venueId": "ven_8",
    "externalReference": "CRM-10492",
    "createdBy": {
      "name": "Alex Planner",
      "email": "[email protected]"
    }
  }, idempotencyKey: crypto.randomUUID() });
console.log(created);

var payload = JsonSerializer.Deserialize<JsonElement>("""
{
  "name": "Smith-Jones Wedding",
  "date": "2027-06-12",
  "type": "wedding",
  "guestCount": 150,
  "venueId": "ven_8",
  "externalReference": "CRM-10492",
  "createdBy": {
    "name": "Alex Planner",
    "email": "[email protected]"
  }
}
""");
using var content = JsonContent.Create(payload, new MediaTypeHeaderValue("application/json"));
using var request = new HttpRequestMessage(HttpMethod.Post, "v1/occasions") { Content = content };
request.Headers.Add("Idempotency-Key", Guid.NewGuid().ToString());
using var response = await http.SendAsync(request);
response.EnsureSuccessStatusCode();
var result = await response.Content.ReadFromJsonAsync<JsonElement>();

Retrieve an occasion

GET/v1/occasions/{occasionId}scope occasions:read

One occasion by id, with an ETag you'll need if you want to update it safely.

Path parameters

Returns

An occasion object.

Example response

{
  "id": "occ_42",
  "name": "Smith-Jones Wedding",
  "date": "2027-06-12",
  "type": "wedding",
  "guestCount": 150,
  "venueId": "ven_8",
  "externalReference": "CRM-10492",
  "createdBy": {
    "name": "Alex Planner",
    "email": "[email protected]"
  },
  "createdAt": "2026-09-17T08:34:06Z",
  "updatedAt": "2026-09-17T08:34:06Z"
}

Notes

• Send If-None-Match: "<etag>" to get a cheap 304 Not Modified when nothing has changed.

Example request

curl -sS "$METIS_BASE/v1/occasions/occ_42" \
  -H "Authorization: Bearer $METIS_API_KEY" \
  -H "Metis-Connection: $METIS_CONNECTION"

const result = await metis("/v1/occasions/occ_42");
console.log(result);

using var response = await http.GetAsync("v1/occasions/occ_42");
response.EnsureSuccessStatusCode();
var result = await response.Content.ReadFromJsonAsync<JsonElement>();

Update an occasion

PATCH/v1/occasions/{occasionId}scope occasions:write

Changes an event Metis already knows about — the date moved, the numbers went up, it switched venue. Send only the fields that changed (JSON Merge Patch, RFC 7396).

Path parameters

Headers

Body fields

Returns

The updated occasion with a new ETag.

Errors worth handling

Notes

• The request Content-Type may be application/merge-patch+json or plain application/json.
• Omitting If-Match is allowed — it just means last write wins.

Example request

curl -sS -X PATCH "$METIS_BASE/v1/occasions/occ_42" \
  -H "Authorization: Bearer $METIS_API_KEY" \
  -H "Metis-Connection: $METIS_CONNECTION" \
  -H 'If-Match: "the-etag-you-last-read"' \
  -H "Content-Type: application/merge-patch+json" \
  -d '{"guestCount": 165, "date": "2027-06-19"}'

const updated = await metis("/v1/occasions/occ_42", { method: "PATCH", body: {
    "guestCount": 165,
    "date": "2027-06-19"
  }, ifMatch: occasion.etag });
console.log(updated);

var payload = JsonSerializer.Deserialize<JsonElement>("""
{
  "guestCount": 165,
  "date": "2027-06-19"
}
""");
using var content = JsonContent.Create(payload, new MediaTypeHeaderValue("application/merge-patch+json"));
using var request = new HttpRequestMessage(HttpMethod.Patch, "v1/occasions/occ_42") { Content = content };
request.Headers.Add("If-Match", etag);   // the ETag you last read
using var response = await http.SendAsync(request);
response.EnsureSuccessStatusCode();
var result = await response.Content.ReadFromJsonAsync<JsonElement>();

List plan requests

GET/v1/plan-requestsscope floorplans:read

Your open and finished plan requests, oldest first. Poll this with ?status=completed to pick up plans your team has finished — the simplest way to keep your system in step until webhooks arrive.

Query parameters

Returns

A page of plan requests. warnings is only filled in when you retrieve a single request.

Example response

{
  "data": [
    {
      "id": "pr_12",
      "occasionId": "occ_42",
      "roomId": "room_26",
      "status": "completed",
      "currentVersion": 2,
      "externalReference": "BEO-7781"
    }
  ],
  "hasMore": false,
  "nextCursor": null
}

Notes

• Poll politely — once every few minutes per connection is plenty. See Rate limits.

Example request

curl -sS "$METIS_BASE/v1/plan-requests?status=completed&occasionId=occ_42" \
  -H "Authorization: Bearer $METIS_API_KEY" \
  -H "Metis-Connection: $METIS_CONNECTION"

const result = await metis("/v1/plan-requests");
console.log(result);

using var response = await http.GetAsync("v1/plan-requests");
response.EnsureSuccessStatusCode();
var result = await response.Content.ReadFromJsonAsync<JsonElement>();

Create a plan request

POST/v1/occasions/{occasionId}/plan-requestsscope floorplans:write

The heart of the integration. Your system sends the room, the layout style and the numbers; Metis creates the plan in your Metis account and puts it on your planners' to-do list. One of them opens it, finishes it properly and marks it complete — and your system gets back a PDF and a PNG to attach to the BEO or the client's proposal. Leave layoutStyle out and Metis just opens the empty room for them.

Path parameters

Headers

Body fields

Returns

201 Created with the plan request in status requested.

Errors worth handling

Notes

• Each plan request uses one of your plan allowance. Don't create speculative requests.
• Room structures themselves never count against the allowance — only the plans made from them.

Example request

curl -sS -X POST "$METIS_BASE/v1/occasions/occ_42/plan-requests" \
  -H "Authorization: Bearer $METIS_API_KEY" \
  -H "Metis-Connection: $METIS_CONNECTION" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"roomId": "room_26", "layoutStyle": "banquet", "layoutOptions": {"tableSize": 10, "danceFloor": true}, "guestCount": 120, "startTime": "19:00", "endTime": "23:30", "notes": "Top table for 12 on the stage side.", "contact": {"name": "Alex Planner", "email": "[email protected]", "phone": "+44 1234 567890"}, "externalReference": "BEO-7781"}'

const created = await metis("/v1/occasions/occ_42/plan-requests", { method: "POST", body: {
    "roomId": "room_26",
    "layoutStyle": "banquet",
    "layoutOptions": {
      "tableSize": 10,
      "danceFloor": true
    },
    "guestCount": 120,
    "startTime": "19:00",
    "endTime": "23:30",
    "notes": "Top table for 12 on the stage side.",
    "contact": {
      "name": "Alex Planner",
      "email": "[email protected]",
      "phone": "+44 1234 567890"
    },
    "externalReference": "BEO-7781"
  }, idempotencyKey: crypto.randomUUID() });
console.log(created);

var payload = JsonSerializer.Deserialize<JsonElement>("""
{
  "roomId": "room_26",
  "layoutStyle": "banquet",
  "layoutOptions": {
    "tableSize": 10,
    "danceFloor": true
  },
  "guestCount": 120,
  "startTime": "19:00",
  "endTime": "23:30",
  "notes": "Top table for 12 on the stage side.",
  "contact": {
    "name": "Alex Planner",
    "email": "[email protected]",
    "phone": "+44 1234 567890"
  },
  "externalReference": "BEO-7781"
}
""");
using var content = JsonContent.Create(payload, new MediaTypeHeaderValue("application/json"));
using var request = new HttpRequestMessage(HttpMethod.Post, "v1/occasions/occ_42/plan-requests") { Content = content };
request.Headers.Add("Idempotency-Key", Guid.NewGuid().ToString());
using var response = await http.SendAsync(request);
response.EnsureSuccessStatusCode();
var result = await response.Content.ReadFromJsonAsync<JsonElement>();

Retrieve a plan request

GET/v1/plan-requests/{planRequestId}scope floorplans:read

The full state of one request: where it has got to, what your planners have been told, any warnings raised while laying out the furniture, and every completed version with fresh download links. This is the call to make when someone opens the booking in your system.

Path parameters

Returns

The plan request, its versions and their links.

Example response

{
  "id": "pr_12",
  "occasionId": "occ_42",
  "roomId": "room_26",
  "floorplanId": "fp_118",
  "status": "completed",
  "statusChangedAt": "2026-09-17T15:12:44Z",
  "layoutStyle": "banquet",
  "layoutOptions": {
    "tableSize": 10,
    "danceFloor": true
  },
  "guestCount": 120,
  "startTime": "19:00",
  "endTime": "23:30",
  "notes": "Top table for 12 on the stage side.",
  "contact": {
    "name": "Alex Planner",
    "email": "[email protected]",
    "phone": "+44 1234 567890"
  },
  "externalReference": "BEO-7781",
  "warnings": [
    {
      "code": "capacity_shortfall",
      "message": "Seated 110 of 120 guests; your team will adjust."
    }
  ],
  "pendingChanges": [],
  "currentVersion": 1,
  "versions": [
    {
      "version": 1,
      "completedAt": "2026-09-17T15:12:44Z",
      "renderStatus": "rendered",
      "renderedAt": "2026-09-17T15:13:02Z",
      "pdfUrl": "https://metisroomplanner.com/MetisEventsApi/v1/plan-requests/pr_12/versions/1/pdf",
      "pngUrl": "https://metisroomplanner.com/MetisEventsApi/v1/plan-requests/pr_12/versions/1/png",
      "pdfShareUrl": "https://metisroomplanner.com/MetisEventsApi/files/plan-requests/pr_12/versions/1.pdf?expires=1792886400&signature=6f21c4a9…",
      "pngShareUrl": "https://metisroomplanner.com/MetisEventsApi/files/plan-requests/pr_12/versions/1.png?expires=1792886400&signature=a03c7be1…"
    }
  ],
  "plannerUrl": "https://metisroomplanner.com/planner/?plan=plan-be8d2591",
  "createdAt": "2026-09-17T09:02:10Z",
  "updatedAt": "2026-09-17T15:13:02Z"
}

Notes

• status moves requested → in_progress → completed, and back to changes_requested if you change the brief afterwards. cancelled is final.
• currentVersion is 0 until the first time the venue completes the plan.
• Share links expire after 30 days; retrieve the plan request again for fresh ones. They are signed URLs — tamper with expires or signature and you get 403 invalid_signature.
• pdfShareUrl and pngShareUrl are null — with no error — on a server where rendering has not been configured, and that is the shipped default. Check for null before you build a feature on them, and use the authenticated pdfUrl/pngUrl if you only need the file server-side.

Example request

curl -sS "$METIS_BASE/v1/plan-requests/pr_12" \
  -H "Authorization: Bearer $METIS_API_KEY" \
  -H "Metis-Connection: $METIS_CONNECTION"

const result = await metis("/v1/plan-requests/pr_12");
console.log(result);

using var response = await http.GetAsync("v1/plan-requests/pr_12");
response.EnsureSuccessStatusCode();
var result = await response.Content.ReadFromJsonAsync<JsonElement>();

Update a plan request

PATCH/v1/plan-requests/{planRequestId}scope floorplans:write

The numbers changed, the dance floor is out, the times moved. Send only what changed and Metis shows your planners exactly which fields differ from the plan they already drew, moving the request to changes_requested if they had finished it. The room can't be changed — cancel and raise a new request instead.

Path parameters

Headers

Body fields

Returns

The updated plan request, including the new pendingChanges entry.

Errors worth handling

Notes

• Changing layoutStyle without also sending layoutOptions drops options that don't apply to the new style.

Example request

curl -sS -X PATCH "$METIS_BASE/v1/plan-requests/pr_12" \
  -H "Authorization: Bearer $METIS_API_KEY" \
  -H "Metis-Connection: $METIS_CONNECTION" \
  -H 'If-Match: "the-etag-you-last-read"' \
  -H "Content-Type: application/merge-patch+json" \
  -d '{"guestCount": 140, "layoutOptions": {"tableSize": 12, "danceFloor": true}}'

const updated = await metis("/v1/plan-requests/pr_12", { method: "PATCH", body: {
    "guestCount": 140,
    "layoutOptions": {
      "tableSize": 12,
      "danceFloor": true
    }
  }, ifMatch: occasion.etag });
console.log(updated);

var payload = JsonSerializer.Deserialize<JsonElement>("""
{
  "guestCount": 140,
  "layoutOptions": {
    "tableSize": 12,
    "danceFloor": true
  }
}
""");
using var content = JsonContent.Create(payload, new MediaTypeHeaderValue("application/merge-patch+json"));
using var request = new HttpRequestMessage(HttpMethod.Patch, "v1/plan-requests/pr_12") { Content = content };
request.Headers.Add("If-Match", etag);   // the ETag you last read
using var response = await http.SendAsync(request);
response.EnsureSuccessStatusCode();
var result = await response.Content.ReadFromJsonAsync<JsonElement>();

Cancel a plan request

POST/v1/plan-requests/{planRequestId}/cancelscope floorplans:write

The booking fell through. Your planners see the request as cancelled and stop work; the plan itself stays in your Metis account. Calling it twice is harmless.

Path parameters

Returns

The cancelled plan request.

Example response

{
  "id": "pr_12",
  "status": "cancelled",
  "statusChangedAt": "2026-09-18T11:00:03Z"
}

Example request

curl -sS -X POST "$METIS_BASE/v1/plan-requests/pr_12/cancel" \
  -H "Authorization: Bearer $METIS_API_KEY" \
  -H "Metis-Connection: $METIS_CONNECTION"

const created = await metis("/v1/plan-requests/pr_12/cancel", { method: "POST" });
console.log(created);

using var content = new StringContent(string.Empty);
using var request = new HttpRequestMessage(HttpMethod.Post, "v1/plan-requests/pr_12/cancel") { Content = content };
using var response = await http.SendAsync(request);
response.EnsureSuccessStatusCode();
var result = await response.Content.ReadFromJsonAsync<JsonElement>();

Redraw the plan from the current brief

POST/v1/plan-requests/{planRequestId}/regeneratescope floorplans:write

Changing a plan takes two calls, on purpose. PATCH changes what you asked for — the guest count went from 120 to 130 — and this redraws the plan to match. They are separate because redrawing throws away any arrangement the venue made by hand, and a change that only needs the venue told should not flatten their work. Read warnings on the response: that is where a capacity shortfall or an extra that could not be placed shows up. The venue still completes the plan before a new version and a new PDF exist.

Path parameters

Query parameters

Returns

The plan request, redrawn.

Example response

{
  "id": "pr_12",
  "guestCount": 130,
  "status": "changes_requested",
  "warnings": [
    {
      "code": "capacity_shortfall",
      "message": "Placed 120 of 130 seats."
    }
  ]
}

Errors worth handling

Example request

curl -sS -X POST "$METIS_BASE/v1/plan-requests/pr_12/regenerate" \
  -H "Authorization: Bearer $METIS_API_KEY" \
  -H "Metis-Connection: $METIS_CONNECTION"

const created = await metis("/v1/plan-requests/pr_12/regenerate", { method: "POST" });
console.log(created);

using var content = new StringContent(string.Empty);
using var request = new HttpRequestMessage(HttpMethod.Post, "v1/plan-requests/pr_12/regenerate") { Content = content };
using var response = await http.SendAsync(request);
response.EnsureSuccessStatusCode();
var result = await response.Content.ReadFromJsonAsync<JsonElement>();

Download a version as PDF

GET/v1/plan-requests/{planRequestId}/versions/{version}/pdfscope floorplans:read

The finished plan as an A4 landscape PDF with a title block — the thing you attach to the BEO or send to the client. Authenticated with your API key, so use it for server-side fetches; for a link you can store or email, use the version's pdfShareUrl instead.

Path parameters

Returns

200 with application/pdf.

Errors worth handling

Example request

curl -sS "$METIS_BASE/v1/plan-requests/pr_12/versions/1/pdf" \
  -H "Authorization: Bearer $METIS_API_KEY" \
  -H "Metis-Connection: $METIS_CONNECTION" \
  -o plan-v1.pdf

const response = await metisRaw("/v1/plan-requests/pr_12/versions/1/pdf");
const bytes = Buffer.from(await response.arrayBuffer());   // save it, or stream it on

var bytes = await http.GetByteArrayAsync("v1/plan-requests/pr_12/versions/1/pdf");
await File.WriteAllBytesAsync("plan-v1.pdf", bytes);

Download a version as PNG

GET/v1/plan-requests/{planRequestId}/versions/{version}/pngscope floorplans:read

The same page as a 1754×1240 image — good for a thumbnail in your booking screen or for embedding in an email.

Path parameters

Returns

200 with image/png.

Errors worth handling

Example request

curl -sS "$METIS_BASE/v1/plan-requests/pr_12/versions/1/png" \
  -H "Authorization: Bearer $METIS_API_KEY" \
  -H "Metis-Connection: $METIS_CONNECTION" \
  -o plan-v1.png

const response = await metisRaw("/v1/plan-requests/pr_12/versions/1/png");
const bytes = Buffer.from(await response.arrayBuffer());   // save it, or stream it on

var bytes = await http.GetByteArrayAsync("v1/plan-requests/pr_12/versions/1/png");
await File.WriteAllBytesAsync("plan-v1.png", bytes);

Download the current version as PDF

GET/v1/plan-requests/{planRequestId}/versions/latest/pdfscope floorplans:read

The newest completed version, worked out when you ask rather than when you last read the request. A numbered version address freezes one revision: store it against a booking and it keeps serving that revision after the plan has been redrawn. This one follows the plan, so you can keep a single address for the life of the booking and never track version numbers. For a link you can put in a document without your API key, use latest.pdfShare from the plan request.

Path parameters

Returns

200 with application/pdf.

Errors worth handling

Example request

curl -sS "$METIS_BASE/v1/plan-requests/pr_12/versions/latest/pdf" \
  -H "Authorization: Bearer $METIS_API_KEY" \
  -H "Metis-Connection: $METIS_CONNECTION" \
  -o plan-v1.pdf

const response = await metisRaw("/v1/plan-requests/pr_12/versions/latest/pdf");
const bytes = Buffer.from(await response.arrayBuffer());   // save it, or stream it on

var bytes = await http.GetByteArrayAsync("v1/plan-requests/pr_12/versions/latest/pdf");
await File.WriteAllBytesAsync("plan-v1.pdf", bytes);

Download the current version as PNG

GET/v1/plan-requests/{planRequestId}/versions/latest/pngscope floorplans:read

As the latest PDF, but the image — for a thumbnail beside a booking that should stay in step with the plan without your system tracking which version is current.

Path parameters

Returns

200 with image/png.

Errors worth handling

Example request

curl -sS "$METIS_BASE/v1/plan-requests/pr_12/versions/latest/png" \
  -H "Authorization: Bearer $METIS_API_KEY" \
  -H "Metis-Connection: $METIS_CONNECTION" \
  -o plan-v1.png

const response = await metisRaw("/v1/plan-requests/pr_12/versions/latest/png");
const bytes = Buffer.from(await response.arrayBuffer());   // save it, or stream it on

var bytes = await http.GetByteArrayAsync("v1/plan-requests/pr_12/versions/latest/png");
await File.WriteAllBytesAsync("plan-v1.png", bytes);

List floorplans

GET/v1/occasions/{occasionId}/floorplansscope floorplans:read

Every floorplan attached to an occasion, including ones your team created directly in Metis rather than through the API.

Path parameters

Returns

The occasion's floorplans in a single page.

Example response

{
  "data": [
    {
      "id": "fp_118",
      "occasionId": "occ_42",
      "name": "Smith-Jones Wedding — Ballroom",
      "roomId": "room_26",
      "externalReference": "BEO-7781",
      "isShared": false,
      "thumbnailUrl": null,
      "updatedAt": "2026-09-17T15:12:44Z"
    }
  ],
  "hasMore": false,
  "nextCursor": null
}

Example request

curl -sS "$METIS_BASE/v1/occasions/occ_42/floorplans" \
  -H "Authorization: Bearer $METIS_API_KEY" \
  -H "Metis-Connection: $METIS_CONNECTION"

const result = await metis("/v1/occasions/occ_42/floorplans");
console.log(result);

using var response = await http.GetAsync("v1/occasions/occ_42/floorplans");
response.EnsureSuccessStatusCode();
var result = await response.Content.ReadFromJsonAsync<JsonElement>();

Retrieve a floorplan

GET/v1/floorplans/{floorplanId}scope floorplans:read

One floorplan by id.

Path parameters

Returns

A floorplan object.

Example response

{
  "id": "fp_118",
  "occasionId": "occ_42",
  "name": "Smith-Jones Wedding — Ballroom",
  "roomId": "room_26",
  "externalReference": "BEO-7781",
  "isShared": false,
  "thumbnailUrl": null,
  "updatedAt": "2026-09-17T15:12:44Z"
}

Example request

curl -sS "$METIS_BASE/v1/floorplans/fp_118" \
  -H "Authorization: Bearer $METIS_API_KEY" \
  -H "Metis-Connection: $METIS_CONNECTION"

const result = await metis("/v1/floorplans/fp_118");
console.log(result);

using var response = await http.GetAsync("v1/floorplans/fp_118");
response.EnsureSuccessStatusCode();
var result = await response.Content.ReadFromJsonAsync<JsonElement>();

Create a floorplan

POST/v1/occasions/{occasionId}/floorplansscope floorplans:write

Copies one of your own saved layouts for a room straight into the occasion, skipping the request-and-complete cycle. Use it when you already have exactly the plan you want. To start from an empty room and have Metis lay it out, use a plan request instead.

Path parameters

Headers

Body fields

Returns

201 Created with the floorplan.

Notes

• Counts toward your Metis plan allowance.
• Nothing is generated and nobody at the venue is asked to finish anything: the copy is an ordinary plan their team can open, edit and print. A layout that is not one of your own returns 422 layout_not_found.

Example request

curl -sS -X POST "$METIS_BASE/v1/occasions/occ_42/floorplans" \
  -H "Authorization: Bearer $METIS_API_KEY" \
  -H "Metis-Connection: $METIS_CONNECTION" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"layoutId": "lay_58", "name": "Smith-Jones Wedding — Ballroom", "externalReference": "BEO-7781"}'

const created = await metis("/v1/occasions/occ_42/floorplans", { method: "POST", body: {
    "layoutId": "lay_58",
    "name": "Smith-Jones Wedding — Ballroom",
    "externalReference": "BEO-7781"
  }, idempotencyKey: crypto.randomUUID() });
console.log(created);

var payload = JsonSerializer.Deserialize<JsonElement>("""
{
  "layoutId": "lay_58",
  "name": "Smith-Jones Wedding — Ballroom",
  "externalReference": "BEO-7781"
}
""");
using var content = JsonContent.Create(payload, new MediaTypeHeaderValue("application/json"));
using var request = new HttpRequestMessage(HttpMethod.Post, "v1/occasions/occ_42/floorplans") { Content = content };
request.Headers.Add("Idempotency-Key", Guid.NewGuid().ToString());
using var response = await http.SendAsync(request);
response.EnsureSuccessStatusCode();
var result = await response.Content.ReadFromJsonAsync<JsonElement>();

Create a link to an occasion

POST/v1/occasions/{occasionId}/linksscope links:create

Opens the occasion's current floorplan — put it behind an 'Open in Metis' button in your UI. An occasion with no floorplan yet returns 409 no_floorplan, which is a different answer from 'no such occasion' and tells you to request one first.

Path parameters

Body fields

Returns

A link, with an expiry when there is one.

Example response

{
  "url": "https://metisroomplanner.com/planner/?plan=plan-be8d2591",
  "expiresAt": null
}

Example request

curl -sS -X POST "$METIS_BASE/v1/occasions/occ_42/links" \
  -H "Authorization: Bearer $METIS_API_KEY" \
  -H "Metis-Connection: $METIS_CONNECTION" \
  -H "Content-Type: application/json" \
  -d '{"purpose": "edit"}'

const created = await metis("/v1/occasions/occ_42/links", { method: "POST", body: {
    "purpose": "edit"
  } });
console.log(created);

var payload = JsonSerializer.Deserialize<JsonElement>("""
{
  "purpose": "edit"
}
""");
using var content = JsonContent.Create(payload, new MediaTypeHeaderValue("application/json"));
using var request = new HttpRequestMessage(HttpMethod.Post, "v1/occasions/occ_42/links") { Content = content };
using var response = await http.SendAsync(request);
response.EnsureSuccessStatusCode();
var result = await response.Content.ReadFromJsonAsync<JsonElement>();

Create a link that opens a floorplan

POST/v1/floorplans/{floorplanId}/linksscope links:create

edit opens the Metis planner — the person must be signed in to your Metis account, so this is for the venue's own team, and the link does not expire. view returns the same key-less, expiring review link as share-links, for everyone else.

Path parameters

Body fields

Returns

A link, with an expiry when there is one.

Example response

{
  "url": "https://metisroomplanner.com/review/shr-7f3a9c21",
  "expiresAt": "2026-09-24T12:00:00Z"
}

Example request

curl -sS -X POST "$METIS_BASE/v1/floorplans/fp_118/links" \
  -H "Authorization: Bearer $METIS_API_KEY" \
  -H "Metis-Connection: $METIS_CONNECTION" \
  -H "Content-Type: application/json" \
  -d '{"purpose": "view"}'

const created = await metis("/v1/floorplans/fp_118/links", { method: "POST", body: {
    "purpose": "view"
  } });
console.log(created);

var payload = JsonSerializer.Deserialize<JsonElement>("""
{
  "purpose": "view"
}
""");
using var content = JsonContent.Create(payload, new MediaTypeHeaderValue("application/json"));
using var request = new HttpRequestMessage(HttpMethod.Post, "v1/floorplans/fp_118/links") { Content = content };
using var response = await http.SendAsync(request);
response.EnsureSuccessStatusCode();
var result = await response.Content.ReadFromJsonAsync<JsonElement>();

Create a shareable review link

POST/v1/floorplans/{floorplanId}/share-linksscope links:create

A link anyone can open without a Metis account, to walk round the plan in 2D and 3D until it expires. Good for sending to the client. The link appears in the account owner's shares list in Metis, named after your integration, and they can revoke it there at any time.

Path parameters

Headers

Body fields

Returns

A link with an expiry.

Example response

{
  "url": "https://metisroomplanner.com/review/shr-7f3a9c21",
  "expiresAt": "2026-09-28T12:00:00Z"
}

Example request

curl -sS -X POST "$METIS_BASE/v1/floorplans/fp_118/share-links" \
  -H "Authorization: Bearer $METIS_API_KEY" \
  -H "Metis-Connection: $METIS_CONNECTION" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"expiresInHours": 168}'

const created = await metis("/v1/floorplans/fp_118/share-links", { method: "POST", body: {
    "expiresInHours": 168
  }, idempotencyKey: crypto.randomUUID() });
console.log(created);

var payload = JsonSerializer.Deserialize<JsonElement>("""
{
  "expiresInHours": 168
}
""");
using var content = JsonContent.Create(payload, new MediaTypeHeaderValue("application/json"));
using var request = new HttpRequestMessage(HttpMethod.Post, "v1/floorplans/fp_118/share-links") { Content = content };
request.Headers.Add("Idempotency-Key", Guid.NewGuid().ToString());
using var response = await http.SendAsync(request);
response.EnsureSuccessStatusCode();
var result = await response.Content.ReadFromJsonAsync<JsonElement>();