Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


Metaphysics is a GraphQL-compliant API that wraps various Artsy APIs. You can try it here against our staging API.

It is built on express, express-graphql, and graphql. With graphiql providing a sandbox to work with.

It is currently used in production all over the place in, and the Artsy iOS App

Meta CircleCI codecov

Getting Setup

To get yourself set up with all the project's dependencies:

git clone
cd metaphysics

# Run the setup script

This will pull the environment variables from aws into .env.shared. It will also overwrite .env with the values in .env.example. If you need to override any of these values or add new .env values place them in the .env file.


With your dependencies set up, you can run Metaphysics by running:

yarn start

Which will start the server on http://localhost:3000

Be sure that memcached is no longer running before starting hokusai by running

brew services stop memcached

Recommended: You can run the commands inside the terminal in VS Code, then the debugger will be hooked up by default.

Setting up your local GraphiQL

We recommend the client for testing queries locally.

You will need to set up headers with both:

  • x-access-token - Open, sign in and evaluate sd.CURRENT_USER.accessToken in a dev console (CMD+Shift+C in Chrome).
  • x-user-id - As above, but

If you're new to GraphQL, you can checkout Artsy's GraphQL Workshop.

For GraphQL Endpoint, set it to http://localhost:3000/v2.

Note that /v2 is the default and /v1 has been fully deprecated and removed.

Introspection Setup

Getting docs for the schema on MP in your playground of choice (Postman, Insomnia, Altair, etc) is called introspection.

Introspection is available by default when developing.

Introspection on staging and production are for internal use only, so artsy devs can use it to make development for MP clients (eigen, force, etc) easier, but it is and should not be used by any of the clients or anyone else.

In order to set this up in your playground of choice (Postman, Insomnia, Altair, etc), you need to send the following header:

Authorization: Bearer <secret>

and replace <secret> with the value you get from hokusai using

hokusai staging env get INTROSPECT_TOKEN
hokusai production env get INTROSPECT_TOKEN

or the contents of Metaphysics INTROSPECT_TOKEN in 1Password.

Sample Queries

Once you have the GraphiQL client running against your local service, you can verify things are working by executing these queries:

Get your account information

  me {

If any of these queries fail, it's probable that you misconfigured your x-access-token or x-user-id HTTP headers.


Docker and Kubernetes setup

This is deployed using Hokusai to manage Docker and Kubernetes. To replicate this:

  • Install Docker for Mac and Hokusai

    $ brew tap caskroom/cask && brew cask install docker
    $ pip install hokusai

    If you are using your system Python distribution, you may need to run this as:

    $ sudo pip install hokusai --ignore-installed
  • Configure Hokusai

    hokusai configure --kubectl-version {{ kubectl_version }} --s3-bucket {{ kubectl_config_s3_bucket }} --s3-key {{ kubectl_config_s3_key }}
    hokusai check

    Artsy staff should find follow the instructions in

  • Start the server

    hokusai dev start


  • Run tests in the Docker Compose test stack via Hokusai:

    hokusai test
  • Or, to run tests locally: npm test to run the entire suite npm run watch to spin up the test watcher

About Artsy

This project is the work of engineers at Artsy, the world's leading and largest online art marketplace and platform for discovering art. One of our core Engineering Principles is being Open Source by Default which means we strive to share as many details of our work as possible.

You can learn more about this work from our blog and by following @ArtsyOpenSource or explore our public data by checking out our API. If you're interested in a career at Artsy, read through our job postings!