API Reference

The Jahuty API is organized around REST. Our API has predictable resource-oriented URLs, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Currently, we only support a single environment.

All requests use the current version of our API. When we make backwards-incompatible changes to the API, which we do our best to avoid, we'll release a new major version and introduce a versioning scheme.

Base URL


The Jahuty API uses API keys to authenticate requests. You can view and manage your organization's API keys from your organization settings.

There are two types of API keys: public and secret. Although public keys are not secret and carry limited priviledges, you should not share them in publicly accessible areas such as Github, Bitbucket, client-side code, and so forth.

Each SDK provides a method to set your organization's API key using a static method or public static variable. Once it's set, it'll be included in subsequent requests automatically.

If you're using the API directly, you can pass your organization's API token via bearer authentication, by setting the Authorization to request header's value to Bearer YOUR_API_KEY.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

To learn more about API keys, see API keys.

Authenticated request
curl \
  https://api.jahuty.com/snippets/1/render \
  -H "Authorization: Bearer kn2Kj5ijmT2pH6ZKqAQyNexUqKeRM4VG6DDgWN1lIcc"; \
Your API key

A sample test API key is included in all the examples here, so you can test any example right away:


To test requests using your account, replace the sample API key with one of your organization's actual API keys.


Jahuty uses conventional HTTP response codes to indicate the success or failure of an API request.

In general: codes in the 2xx range indicate success; codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, the resource does not exist, etc.); and, codes in the 5xx range indicate an error with Jahuty's servers (these are rare).

When an error does occur, the Jahuty API will respond with the application/problem+json content type.

HTTP status codes
200 - OK
Everything worked as expected.
401 - Unauthorized
No valid API key provided.
402 - Payment Required
Your free trial or subscription has expired.
403 - Forbidden
The API key doesn't have permissions to perform the request.
404 - Not Found
The requested resource doesn't exist.
500, 502, 503, 504 - Server Errors
Something went wrong on Jahuty's end. (These are rare.)


Jahuty uses the application/problem+json resource to describe errors.

status integer
The original HTTP status code.
title string
A short, human-readable title for the general error type.
detail string
A human-readable description of the specific error.
type string
A URL to more information about the reported error.
Error object
  "status": 404,
  "title": "Not found",
  "detail": "The requested resource was not found",
  "type": "https://en.wikipedia.org/wiki/List_of_HTTP_status_codes"

Handling errors

Our SDKs raise exceptions for errors that need your attention such as invalid parameters or authentication errors.

We don't recommend writing code that handles API exceptions. An exception will likely only occur in a situation which requires your attention.

Handling exceptions
use Jahuty\Jahuty\Jahuty;
use Jahuty\Jahuty\Snippet;
use Jahuty\Jahuty\Exception\NotOk;


try {
  // Returns 404 (raising exception) because snippet and key do not match.
} catch (NotOk $e) {
  $p = $e->getProblem();

  echo $p->getStatus();
  echo $p->getType();
  echo $p->getDetail();
Handling exceptions
require "jahuty"

Jahuty.key = "kn2Kj5ijmT2pH6ZKqAQyNexUqKeRM4VG6DDgWN1lIcc"

  # Responds 404 (raising exception) because snippet and key do not match.
  Snippet.get 999
rescue Jahuty::Exception::NotOk => e
  p = e.problem

  puts p.status
  puts p.type
  puts p.detail


A snippet is a small piece of text or HTML you manage through our website; render using our SDKs or API; and, display in your application on-demand. Each snippet is assigned a unique identifier (aka, id) that you'll use to refer to it.

GET /snippets/:id

Render a snippet

Renders a snippet's content using the passed parameters. You need only supply the unique identifier that was assigned to the snippet upon creation.


id integer
The identifier of the snippet to retrieve.
params string optional
A URL-encoded, JSON string of parameters to use. Passed via the params query string parameter. Unused variables are ignored.


Returns a rendered snippet. When requesting a snippet that does not exist or you are not authorized to access, a 404 error will be returned.

GET snippets/:id/render
  https://api.jahuty.com/snippets/1/render \
  -H "Authorization: Bearer kn2Kj5ijmT2pH6ZKqAQyNexUqKeRM4VG6DDgWN1lIcc"; \
GET snippets/:id/render
use Jahuty\Jahuty\{Jahuty, Snippet};


echo Snippet::render(1, [
  "params" => [
    "foo" => "bar"
GET snippets/:id/render
require "Jahuty"

Jahuty.key = "kn2Kj5ijmT2pH6ZKqAQyNexUqKeRM4VG6DDgWN1lIcc"

puts Jahuty::Snippet.render 1, params: { "foo": "bar" }
  "content": "This is my first snippet!"

Find a typo? Something is wrong in this documentation? Fork and edit it!