Introduction

Developers can interact with the complete smarter.sh/v1 API, which includes significantly more platform functionality than what is available in the base command set offered by the CLI . See the API Technical Reference for details on the available endpoints and their usage.

You can interact with the Smarter API through any language that supports the http and REST API protocols, including for example Python, Javascript and Golang. All API operations are journaled by default, and can be viewed by any account admin from the Admin Console . Journal data rention policies are configurable and are managed at the account level. The API returns all responses in JSON format, following the smarter.sh/v1 API schema. For example:

              
  {
    "api": "smarter.sh/v1",
    "data": {
        "account": {
            "account_number": "3141-5926-5359",
            "address1": "1700 South Lamar Blvd",
            "address2": "Suite 338",
            "city": "Austin",
            "company_name": "Smarter",
            "country": "USA",
            "created_at": "2024-05-24T21:22:52.712547Z",
            "currency": "USD",
            "id": 1,
            "language": "",
            "phone_number": "+1 (512) 833-6955",
            "postal_code": "78704",
            "state": "TX",
            "timezone": "America/Chicago",
            "updated_at": "2024-06-07T00:51:27.369962Z"
        },
        "user": {
            "email": "admin@smarter.sh",
            "first_name": "",
            "id": 1,
            "is_staff": true,
            "is_superuser": true,
            "last_name": "",
            "username": "admin"
        }
    },
    "metadata": {
        "command": "whoami"
    },
    "thing": "None"
  }
              
            

Authentication

The Smarter API uses API keys for authentication. You can create API keys from the admin console . These can be created at the Account or User level. Account key should be used to provision access for production systems. Api keys are formatted as a 64-character sha256 hash, such as 548de94hc4f1762c64732d268a2ee2635b2d36e9f7e3be91f1662d5456ae110d .

Remember that your API key is a secret! Do not share it with others or expose it in any client-side code (browsers, apps). Production requests must be routed through your own backend server where your API key can be securely loaded from an environment variable or key management service.

All API requests should include your API key in an Authorization HTTP header as follows:

                
  Authorization: Token $SMARTER_API_KEY
                
            

Making Requests

You can paste the command below into your terminal to run your first API request. Make sure to replace $SMARTER_API_KEY with your secret API key.

Hello world:

                
  curl https://platform.smarter.sh/api/v1/cli/whoami/ \
  -H "Authorization: Token $SMARTER_API_KEY" \
                
              

Apply a manifest:

                
  curl https://platform.smarter.sh/api/v1/cli/apply/ \
  -H "Content-Type: application/json" \
  -H "Authorization: Token $SMARTER_API_KEY" \
  -d 'MANIFEST DATA HERE'