API

What follows is the guide to our API.

NOTES

• 🔐 means the endpoint requires an Authentication header with a value like "JWT <authToken>". See examples.
• Every request to the API should include a Content-Type header with the value of application/json.

Contents

User

Create

Session

Create

StoryJob

Create

Story

Primary Story

---

User

Create

---

Creating a new User via our API

• URL

  /api/:version/users

• Method

  POST

• Headers

  Content-Type=application/json

• URL Params

  Reqired:

  version=[integer]

• Query String Params

  N/A

• Data Params

  Reqired:

  {
      "username": [string],
      "email": [string],
      "password": [string]
  }
  

• Success Response:

  Code: 200
  Content:

  {
    "user": {
      "id": [integer],
      "username": [string],
      "email": [string],
      "createdAt": [datestring],
      "updatedAt": [datestring],
      "authToken": [string]
    }
  }
  

• Error Response:

  Code: 422 UNPROCESSABLE ENTRY
  Content:

  { status : 422, message : [string] }
  

• Sample Call:

  $.post("/api/v1/users", { 
      "username": "yakamoto", 
      "email": "[email protected]",
      "password": "godmode"
  });
  

• Notes:

  Currently doesnt require the user be signed out (which essentially means that it doesnt check if a valid JWT token was passed with the request. Might want to add that in.

---

---

---

Session

Create

---

Authenticating a User via our API

• URL

  /api/:version/login

• Method

  POST

• Headers

  Content-Type=application/json

• URL Params

  Reqired:

  version=[integer]

• Query String Params

  N/A

• Data Params

  Reqired:

  {
      "username": [string],
      "password": [string]
  }
  

• Success Response:

  Code: 200
  Content:

  {
    "user": {
      "id": [integer],
      "username": [string],
      "email": [string],
      "active": true,
      "createdAt": [datestring],
      "updatedAt": [datestring],
      "authToken": [string]
    }
  }
  

• Error Response:

  Code: 422 UNPROCESSABLE ENTRY
  Content:

  { status : 422, message : [string] }
  

• Sample Call:

  $.post("/api/v1/login", { 
      "username": "yakamoto", 
      "password": "godmode"
  });
  

• Notes:

  For the post params, the API requires that the username key be "username". However, the API does allow that the user pass in their email instead here. Authentication will try to sign the user in treating the "username" value as an email if it initially fails to find a user by the given username value.

---

---

---

StoryJob

Create

---

Creating a new StoryJob

• URL

  /api/:version/story_jobs 🔐

• Method

  POST

• Headers

  Content-Type=application/json

• URL Params

  Reqired:

  version=[integer]

• Query String Params

  N/A

• Data Params

  N/A

• Success Response:

  Code: 200
  Content:

  {
    "storyJob": {
      "referenceId": [string]
    },
    "aws": {
      "credentials": {
        "accessKeyId": [string],
        "secretAccessKey": [string],
        "sessionToken": [string],
        "expiration": [datestring]
      }
    }
  }
  

• Error Response:

  Code: 401 UNAUTHORIZED
  Content: N/A

• Sample Call:

  // authToken = authToken returned from previous login;
  $.ajax({  
      url: "/api/v1/story_jobs",   
      type: "post",
      data: { },
      headers: {"Authorization": "JWT " + authToken}
  });
  

• Notes:

Story

Primary Story

---

Getting the primary story for a user

• URL

  /api/:version/stories/primary_story

• Method

  GET

• Headers

  Content-Type=application/json

• URL Params

  N/A

• Query String Params

  Optional:

  username=[string]

  userId=[integer]

• Data Params

  N/A

• Success Response:

  Code: 200
  Content:

  {
      "story": {
          "id": [integer],
          "primaryStory": true,
          "outputKeyPrefix": [string],
          "storyMedia": [
              {
                  "id": [integer],
                  "key": [string],
                  "url": [string],
                  "type": [string],
                  "width": [integer],
                  "height": [integer],
                  "duration": [integer],
                  "createdAt": [datestring],
                  "updatedAt": [datestring],
                  "storyId": [integer]
              },
              ...
          ],
          "active": true,
          "createdAt": [datestring],
          "updatedAt": [datestring],
          "userId": [integer],
          "storyJobId": [integer]
      }
  }
  

• Error Response:

  Code: 404 NOT FOUND
  Content:

  { status : 404, message : [string] }
  

• Sample Call:

  $.ajax({  
      url: "/api/v1/stories/primary_story?username=yakamoto",   
      type: "get"
  });
  

• Notes: