🖥️

API - for developers

Hack the planet
Did You Know? Developers are super cool
Glif API is in early beta but we’re excited to see what y'all build ¯¯\(ツ)/¯¯
Generate your API tokens here: https://glif.app/settings/api-tokens
For questions please join our Discord or get in touch. If you've made something cool, let us know! We'd love to promote it.
Some glif-powered things:

Simple API - “just run a glif”

the Simple API allows for a limited # of unauthenticated requests, but you will want to register and pass you own API tokens at https://glif.app/settings/api-tokens -
During limited beta, the Glif API is free, has relatively low rate limits. This is all subject to change. If you're building with our API, please join our Discord or get in touch since we'd love to chat.

Authentication headers

We use Bearer-style auth. After you've created an API token, you can pass it in the "Authorization" HTTP header like so:
curl -X POST -H "Authorization: Bearer abzfasdf2349820349" -d '{}' https://simple-api.glif.app/clgh1vxtu0011mo081dplq3xs
For brevity we're omitting this from subsequent examples, but please provide auth headers. We will turn off unauthenticated requests in the future.

Simple curl example

Here’s an example request using curl:
curl -X POST -d '{"inputs": ["cute friendly oval shaped bot friend"]}' https://simple-api.glif.app/clgh1vxtu0011mo081dplq3xs
Here’s the expected output of that command:
{
"id": "clgh1vxtu0011mo081dplq3xs",
"inputs": { "node_6": "cute friendly oval shaped bot friend" },
"output":"<https://res.cloudinary.com/dzkwltgyd/image/upload/v1686242317/glif-run-outputs/fhbvbp9bwf0pkmm4woj2.png>",
"outputFull": { "...": "" }
}
You're most likely interestd in the output field, which is the final output of the glif. outputFull is a JSON object with more info about the final output, including it's type.
If there’s an error it’ll be in an error field, but still use a "200 OK" status code. For legacy reasons the the Simple API always returns 200 OK. This might change in the future.

Parameters

There are many ways to pass input values to a glif. Maybe too many.
The simplest is an array in a field named inputs, like this:
{
"inputs": ["i am the walrus"]
}
You can also POST directly to simple-api.glif.app with no id in the path, and specify the id inside the payload, like:
{
"id": "clgh1vxtu0011mo081dplq3xs",
"inputs": ["I am the walrus"]
}
The inputs parameter is fairly flexible and tries to accomodate a lot of different ways of providing data to the glif.
For a single-input glif, you can just specify a single string. Using an array is recommended but not required:
{
"inputs": ["a happy horse"]
}
For a multi-input glif, you can use a positional array like:
{
"inputs": ["a happy horse", "living on a farm", "in France"]
}
If you forget the "inputs" key and pass a raw string or array, it'll work too, but this could change and isn't recommended:
curl -X POST -d '["cute friendly oval shaped bot friend"]' https://simple-api.glif.app/clgh1vxtu0011mo081dplq3xs
Alternately, you can build a full JSON object with the actual internal parameter names of each input field:
{
"inputs": {
"subject": "a happy horse",
"actionName": "living on a farm",
"location": "in France"
}
}
And lastly, if you are specifying parameter names explicitly, you can leave off the inputs key and just pass the object to your glif, like this:
{
"subject": "a happy horse",
"actionName": "living on a farm",
"location": "in France"
}

Looking up the internal names of a glif's inputs

To specify named parameters, you need to use the internal block name. This has no spaces and usually is something like "text1", "multipick2", but each glif creator can customize it.
On the glif.app website you can look at the block names in the "View source" page of a glif, like this one:
Or you can look at the nodes field of a glif via our API:
https://glif.app/api/glifs?id=clkbasluf0000mi08h541a3j4 This Glif has blocks with the names:
username
ego
radmilk
text1
Full example Glif API response JSON
[
{
"id": "clkbasluf0000mi08h541a3j4",
"name": "chat.welcome",
"imageUrl": null,
"description": "",
"createdAt": "2023-07-20T15:19:11.511Z",
"updatedAt": "2023-12-01T11:59:23.279Z",
"output": "Welcome to our Discord Chat, @jamiedubs, where creativity's at!\nWith Tanaki as your guide, prepare for a delightful ride.\nWe'll connect ideas across the land, with art and magic at our command.\nSo join us now, let's collaborate, and create wonders that resonate.",
"outputType": "TEXT",
"forkedFromId": null,
"featuredAt": null,
"userId": "cli4waaz20002l5082wrs99bx",
"completedSpellRunCount": 3,
"user": {
"id": "cli4waaz20002l5082wrs99bx",
"name": "tanaki",
"image": "https://cdn.discordapp.com/avatars/1111720492408262686/a355dbcf07ce472fc7bc382cf0807802.png",
"username": "tanaki"
},
"forkedFrom": null,
"spheres": [],
"data": {
"nodes": [
{
"name": "username",
"type": "TextInputBlock",
"params": {
"label": "@username to greet",
"value": "harrystyles"
}
},
{
"name": "ego",
"type": "GlifBlock",
"params": {
"id": "clj359oq70000le08nog0a0sb",
"inputValues": []
}
},
{
"name": "radmilk",
"type": "GlifBlock",
"params": {
"id": "clpmk3e3x000xqrpfuxrjq6gl",
"inputValues": []
}
},
{
"name": "text1",
"type": "GPTBlock",
"params": {
"api": "chat",
"model": "gpt-4",
"prompt": "{ego}\nplease keep the above in mind.\n\nI need you to welcome a new user to a discord chat.\n\nAdd a joke in the style of some example jokes. Share the joke as if it were a fact and you are mitch hedberg. Make it weird and under 2 sentences. Don't mention it is a joke. Just tell the joke. Play with their name. Add linebreaks and markdown to format your message where needed.\n\nExample jokes:\n{radmilk}\n\n\nTheir username is:\n{username}\n\nNow write the welcome message in no more than 2 short sentences:\n\n",
"maxTokens": 500,
"temperature": 0.9
}
}
]
},
"_count": {
"likes": 0,
"forks": 0
}
}
]
Lastly, you can use the commandline to fetch field names dynamically using curl + jq:
curl -s https://glif.app/api/glifs?id=clmdnx8fa0000lf0fbovo8lv1 | jq -r '.[] .data .nodes[] .name'
here's the output:
input1
image1
meaning this glif requires two inputs, input1 and image1. We plan to improve this in the near future. In the meantime, try the Simple API above

Default value substitution

If you do not provide enough inputs, the default values in the glif values will be automatically substituted. So if you specify arg1, that'll be used, but if it requires arg1 and arg2, it'll use your arg1 but use the defualt value for arg2.
If you'd prefer to have API calls with insufficient inputs to fail, append ?strict=1 to your URLs, e.g. https://simple-api.glif.app?strict=1

Other API endpoints

These endpoints are alpha-quality and subject to change
Eg for fetching info about a specific glif, user, or a specific glifRun.
Paginate using ?page= when applicable

Individual glif

  • fetch a specific glif: GET https://glif.app/api/glifs?id=clgh1vxtu0011mo081dplq3xs
  • includes data on its most recent runs

Lists of glifs

  • fetch all available glifs: GET https://glif.app/api/glifs
  • fetch featured glifs on homepage: GET https://glif.app/api/glifs?featured=1
  • fetch glifs created by a user (note: no username support yet): GET https://glif.app/api/glifs?userId=flkjasdflkjasdflkj
  • search - very basic, non-fuzzy: GET https://alpha.glif.xyz/api/glifs?query=FOO

User info

  • none at this time, just list of glifs (above)

CORS (Cross-origin requests)

CORS is allowed by the Simple API, but not by our other API endpoints. You'll need to make your own serverside wrappers for these cases.

Example code and apps

NextJS

Here is an example NextJS app that has its own local /api/glif API endpoint:

Simple HTML + CSS (Replit)

Here is a simple pure HTML + CSS + vanilla javascript app hosted on Replit that you can fork and run right there: https://replit.com/@jamiedubs/FishShop

Cloudflare Worker

Since that repl app is pure HTML and doesn’t have its own API, we’re using a Cloudflare Worker serverless function to handle talking to the Glif API w/ CORS headers set:
The “Simple API” above is basically just this code with a shared API token.