API Documentation

Background

Our service enables you to turn images into Augmented Reality USDZ files using a process called photogrammetry. We call these "AR Experiences".

The workflow for creating new USDZ files is:

  1. Upload photos to USDZ.app
  2. Create a new Experience. The Experience Object wraps & describes your USDZ files.
  3. Call the "Build Experience" endpoint that creates your USDZ file(s) and attach it to your Experience Object.
BASE URL
https://usdz.app

Authentication

We use a token-based authentication HTTP authentication scheme called Bearer authentication. This involves sending this token in the Authorization header when making requests to our API.

Create API Token

Authenticated Request
curl "https://usdz.app/api/v1/me" \
-H "Accept: application/json" \
-H "Authorization: Bearer YOUR-TOKEN"
RESPONSE
{
    "account_id": 1,
    "id": 56,
    "user_id": 1
}
Image Created with Sketch.

Images

For speed we allow you to upload Images direct to our AWS S3 bucket. This is accompished with a presigned URL.

The Image Object

Attributes
file_url string
The URL to the image file
guid string
An GUID identifier used for the image
created_at datetime
When the image was first created.
uploaded boolean
Whether the image file has been uploaded. An image object gets created when a request for a presigned_url is made. The uploaded attribute is true when the presigned_url is used to upload an image.
id bigint
The ID of the image. This ID is used for retrieving, updating and deleting the image.
updated_at datetime
When the experience was last updated.
user_id bigint
The ID of the user that created the image. This is distinct from the account_id.
account_id bigint
The ID of the account that created the image.
RESPONSE
{
    "account_id": 1,
    "approved": false,
    "created_at": "2021-09-28T13:48:41.360+10:00",
    "description": null,
    "id": 6,
    "poster": "https://images.usdz.app/4d5aa50029/poster.png",
    "likes_count": 0,
    "short_code": "4d5aa50029",
    "title": "my title",
    "updated_at": "2021-09-28T13:48:41.360+10:00",
    "user_id": 1,
    "views_count": 0
}

Get Presigned URL

This action returns a presigned URL that can be used to upload an image to our S3 bucket.

Parameters

No parameters

Returns

Returns JSON containing the URL for a PUT request.

GET /api/v1/presigned_url
curl "https://usdz.app/api/v1/presigned_url" \
-H "Authorization: Bearer YOUR-TOKEN"
RESPONSE
{
 "method": "put",
 "url": "https://images-usdz.s3-accelerate.amazonaws.com/....",
 "headers":
 [
     {
         "Content-Type": "image/heic"
     }
 ]
}

Uploading an image

Upload an image to our S3 bucket using the presigned URL provided in the above.

Parameters

No parameters

Returns

HTTP/1.1 200 OK

PUT PRESIGNED_URL
curl PRESIGNED_URL \
--upload-file ./path/to/your/photo.heic

Delete an Image

Permanently deletes an image. It cannot be undone.

Parameters

No parameters

Returns

Returns HTTP status OK.

DELETE /api/v1/images/:id
curl "https://usdz.app/api/v1/images/:id" \
-X "DELETE" \
-H "Authorization: Bearer YOUR-TOKEN"
Experience2 Created with Sketch.

Experiences

Experiences objects are used for creating and sharing AR USDZ experiences. The API allows you to create, delete, and update your AR experiences. You can retrieve individual experiences as well as a list of all your experiences.

The Experience Object

Attributes
account_id integer
The ID of the account that owns the experience.
approved boolean
Whether the experience has been approved to be displayed on the usdz.app explore section. An experience will automatically be approved after being reviewed by USDZ.app staff for quality   NSFW issues.
created_at datetime
When the experience was first created.
description string (rendered markdown)
Text that is displayed under the experience and is used to explain and describe the experience.
id bigint
The ID of the experience. This ID is used for retrieving, updating and deleting the experience.
poster string
A URL to the poster for the experience.
likes_count integer
The number of times the experience has been 'liked' by our community.
short_code string
The shortcode is used to access the experience. The shortcode becomes part of the URL.
updated_at datetime
When the experience was last updated.
user_id bigint
The ID of the user that created the experience. This is distinct from the account_id.
views_count integer
The number of times the experience has been viewed by others.
RESPONSE
{
    "account_id": 1,
    "approved": false,
    "created_at": "2021-09-28T13:48:41.360+10:00",
    "description": null,
    "id": 6,
    "poster": "https://images.usdz.app/4d5aa50029/poster.png",
    "likes_count": 0,
    "short_code": "4d5aa50029",
    "title": "my title",
    "updated_at": "2021-09-28T13:48:41.360+10:00",
    "user_id": 1,
    "views_count": 0
}

Get all Experiences from the "Public Feed"

Retrieves the Experiences from the Public Feed. This includes Experiences from all users that have passed moderation.

Parameters
limit integer
The number of experience records to return.
page integer
The page to return.
Attributes
experiences array
An array of Experience Objects
meta.current_page integer
The current page returned.
meta.limit integer
The limit of records being returned.
meta.page_count integer
The number of pages available to be returned (using the above limit).
meta.records integer
The total number of Experience records available.
GET /api/v1/experiences/feed
curl "https://usdz.app/api/v1/experiences/feed?page=1&limit=1" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR-TOKEN"
RESPONSE
{
  "experiences":
  [
    {
      "account":
      {
        "id": 1,
        "name": "Marcus Schappi"
      },
      "account_id": 1,
      "created_at": "2021-09-28T13:48:19.671+10:00",
      "description": null,
      "id": 4,
      "likes_count": 0,
      "medium_progress": 0.0,
      "poster": "https://images.usdz.app/coming-soon.png",
      "preview_progress": 0.0,
      "progress": 0.0,
      "reduced_progress": 0.0,
      "session_status": null,
      "short_code": "1c89acba9e00c1f4fd3d",
      "title": "my title",
      "updated_at": "2021-09-28T13:48:19.671+10:00",
      "url": "https://experiences/4.json",
      "usdz_files":
      [],
      "user":
      {
        "id": 1,
        "name": "Marcus Schappi"
      },
      "user_id": 1,
      "views_count": 0
      
  ],
  "meta":
  {
      "current_page": "3",
      "limit": 1,
      "page_count": 5,
      "records": 5
  }
}

Get all Experiences

Retrieves the user's experiences.

Parameters
limit integer
The number of experience records to return.
page integer
The page to return.
Attributes
experiences array
An array of Experience Objects
meta.current_page integer
The current page returned.
meta.limit integer
The limit of records being returned.
meta.page_count integer
The number of pages available to be returned (using the above limit).
meta.records integer
The total number of Experience records available.
GET /api/v1/experiences
curl "https://usdz.app/api/v1/experiences?page=1&limit=1" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR-TOKEN"
RESPONSE
{
  "experiences":
  [
    {
      "account":
      {
        "id": 1,
        "name": "Marcus Schappi"
      },
      "account_id": 1,
      "created_at": "2021-09-28T13:48:19.671+10:00",
      "description": null,
      "id": 4,
      "likes_count": 0,
      "medium_progress": 0.0,
      "poster": "https://images.usdz.app/coming-soon.png",
      "preview_progress": 0.0,
      "progress": 0.0,
      "reduced_progress": 0.0,
      "session_status": null,
      "short_code": "1c89acba9e00c1f4fd3d",
      "title": "my title",
      "updated_at": "2021-09-28T13:48:19.671+10:00",
      "url": "https://experiences/4.json",
      "usdz_files":
      [],
      "user":
      {
        "id": 1,
        "name": "Marcus Schappi"
      },
      "user_id": 1,
      "views_count": 0
      
  ],
  "meta":
  {
      "current_page": "3",
      "limit": 1,
      "page_count": 5,
      "records": 5
  }
}

Create an Experience

Parameters
title string
The title or name of the experience
description string
A description about the experience
POST /api/v1/experiences
curl -d "{\"experience\":{\"title\":\"my title\"}}" \
"https://usdz.app/api/v1/experiences" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR-TOKEN"
RESPONSE
{
    "account_id": 1,
    "approved": false,
    "created_at": "2021-09-28T13:48:41.360+10:00",
    "description": null,
    "id": 6,
    "likes_count": 0,
    "short_code": "4d5aa50029",
    "title": "my title",
    "updated_at": "2021-09-28T13:48:41.360+10:00",
    "user_id": 1,
    "views_count": 0
}

Retrieve an Experience

Retrieves the details of an existing experience. You need only supply the unique experience that was returned upon experience creation.

Parameters

No parameters

Returns

Returns an experience object if a valid identifier was provided.

GET /api/v1/experiences/:id
curl "https://usdz.app/api/v1/experiences/:id" \
-H "Authorization: Bearer YOUR-TOKEN"
RESPONSE
{
    "account_id": 1,
    "approved": false,
    "created_at": "2021-09-28T13:48:41.360+10:00",
    "description": null,
    "id": 6,
    "poster": "https://images.usdz.app/4d5aa50029/poster.png",
    "likes_count": 0,
    "short_code": "4d5aa50029",
    "title": "my title",
    "updated_at": "2021-09-28T13:48:41.360+10:00",
    "user_id": 1,
    "views_count": 0
}

Update an Experience

Updates the specified experience by setting the values of the parameters passed. Any parameters not provided will be left unchanged. For example, if you pass the title parameter, that becomes the new title. This request accepts mostly the same arguments as the experience creation call.

Parameters
title string
The title or name of the experience
description string
A description about the experience
PATCH /api/v1/experiences/:id
curl -d "{\"experience\":{\"title\":\"my new title\"}}" \
"https://usdz.app/api/v1/experiences/:id" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR-TOKEN"
RESPONSE
{
    "account_id": 1,
    "approved": false,
    "created_at": "2021-09-28T13:48:41.360+10:00",
    "description": null,
    "id": 6,
    "poster": "https://images.usdz.app/4d5aa50029/poster.png",
    "likes_count": 0,
    "short_code": "4d5aa50029",
    "title": "my title",
    "updated_at": "2021-09-28T13:48:41.360+10:00",
    "user_id": 1,
    "views_count": 0
}

Build an Experience

This method "builds" an experience by starting an object capture session for an existing experience.

Parameters

No parameters

Returns

Returns a session_id which can be used to view the status of a build job.

POST /api/v1/experiences/:id/build
curl "https://usdz.app/api/v1/experiences/:id/build" \
-X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR-TOKEN"
RESPONSE
{"session_id": 154}

Like an Experience

This method adds a "like" by the current user to an existing Experience. A user can only "like" an experience once.

Parameters

No parameters

Returns

Returns HTTP status OK.

POST /api/v1/experiences/:id/like
curl "https://usdz.app/api/v1/experiences/:id/like" \
-X POST \
-H "Accept: application/json" \
-H "Authorization: Bearer YOUR-TOKEN"

Unlike an Experience

This method remove a "like" from an Experience previously liked by the current user.

Parameters

No parameters

Returns

Returns HTTP status OK.

DELETE /api/v1/experiences/:id/unlike
curl "https://usdz.app/api/v1/experiences/:id/unlike" \
-X DELETE \
-H "Accept: application/json" \
-H "Authorization: Bearer YOUR-TOKEN"

Delete an Experience

Permanently deletes an experience. It cannot be undone.

Parameters

No parameters

Returns

Returns HTTP status OK.

DELETE /api/v1/experiences/:id
curl "https://usdz.app/api/v1/experiences/:id" \
-X "DELETE" \
-H "Authorization: Bearer YOUR-TOKEN"