HTTP API upgrade

Hey everyone, we’re making a significant upgrade to the map format, which means you’ll need to update your http API usage. I’ve set it up so everyone can transition at their own pace when they’re ready.

As soon as convenient, please:

  • Transition any use of the v1 http API (/api/getMap) to the v2 (/api/v2/spaces/:space/maps/:map). This was a shift we made years ago but I’m finally going to delete the old endpoints and there are still a few stragglers.
  • With the v2 API, pass useV2Map=true as a query param and confirm that your stuff still works. The examples in the docs have already been updated.

Here are the changes between this and the previous version:

  • spaces and desks are not allowed, only nooks (previously auto-converted).
  • objects are now an object, with base64-url-safe (a-zA-Z0-9-_) string keys of length <5. Each one is the same as before plus one new required field, zIndex (>=0), which determines what’s on top, instead of the array order in the previous version.
  • The objects in objects are now validated more, including requiring x, y, normal, type, width, and height on all of them.

Once everyone has had a chance to migrate, I will make useV2Map=true the default behavior, remove support for the old format, and you won’t need to pass that param any more.

If you need more than two weeks to update, DM me and I’ll make sure to wait for you.

Feel free to reply in this thread with any questions!


Hello! Is there any kind of API description document available, such as an OpenAPI description file or similar?


The notion site is about all there is. Here

Thanks Bill!

I should have mentioned, I’m aware of the “Gather HTTP API” Notion page and appreciate the documentation there, but was wondering if there is anything like a OpenAPI description file to act as a source of truth and that we could generate a client from.

It sounds like the answer is no so that’s all good.

Is there any official stance on whether we might get such a thing down the line or if it is in fact a non-goal?

Thanks again!

Yeah sorry nothing like that exists at the moment, and we don’t have any plans to add it in the near future. Let me know if there’s any way that Notion doc could be clearer though!

1 Like

Hi, first of all thank you for updating the api. then, any ideas why this is happening?

`    "error": "UNKNOWN",`
`    "message": "An unknown error has occurred."`

the body

the headers

and the url

It’s the spaceId – %2F is /, but should be \ (%5C). Sorry about that… We keep tripping over this internally too but space ids are so deeply ingrained it’s really hard to fix

Also sorry this error is so unhelpful – I’ll fix it.

Hi everyone,

Has anyone been able to get a successful response from a POST setMap v2 recently? I used a REST API call last Friday that worked great. I saved that request in Postman and haven’t changed it at all since then.

Trying to run it again results in a 500 Internal Server Error / 404 - Not Found.

Did something change since last Friday @npfoss?

Not sure why this isn’t working for me anymore. If anyone else has POST setMap v2 working currently, could you reply here? I believe I checked every possible mistake, but I could be wrong.

Thank you!

Looking into it now! (But I don’t think anything should have changed…)

It works fine for me (using axios in nodejs, the example in the docs) and no recent changes really make sense to have caused this – can you double check again?

Thanks for checking @npfoss! Since you confirmed it is working for you, we tried looking outside of the URL syntax, and we found that one of my devs used his API key, and it wasn’t provisioned for that space. However, we were only getting the 500 / 404 Not found error. That made us think we had something wrong with the URL or the endpoint was down. I do recall in the past, providing no key or an incorrect key would respond with an authentication specific error. Is this intended or just something that shifted with the upgrade to v2? In any case, we got it working now! You’re the best, thank you!

1 Like

Oh huh yeah that isn’t super helpful. I’ll see about fixing the error code


I used in the past the objectStartTime and objectExpireTime to make objects appear and disappear in Gather. I have seen that this option is not anymore available in MapMaker and it also doe snot seem to work when I upload a room using the new API. Is this feature still available?

Thanks and regards.

Unfortunately, those features have been removed from Objects. Currently, the only way to implement that style of object control is through the API and an externally running script.


Im facing a weird bug with the new http setmap In postman all works well with the same url, headers and payload. But doing that same request with tells me that the space was not found :frowning_with_open_mouth: I’m thinking that it is the way the url is formatted and that postman is doing some encoding automatically.
From my perspective, the request on is identical to that in postman…
Any other ideas?

yeah sorry, this just seems like a url encoding difference or something – I don’t have experience with Make so can’t be more helpful, sorry!

1 Like