Skip to main content

GraphQL API

The Uthana GraphQL API provides a flexible way to query and mutate animation data.

Endpoint

https://uthana.com/graphql

Authentication

Include your API key in the basic Authorization header, base64-encoded with a colon:

AUTH_STRING=$(echo -n "<your-api-key>:" | base64)
curl -H "Authorization: Basic $AUTH_STRING" \
https://uthana.com/graphql

or in the query string (plaintext):

https://uthana.com/graphql?api_key=<your-api-key>

Schema

Queries

type Query {
# Get the current user's organization
org: Org

# Get the current user
user: User

# List all characters available to the user
characters: [Character!]

# Get a motion by ID
motion(id: String): Motion

# List motions, with optional filters
motions(
character_id: String
app_ids: [String!]
methods: [String]
): [Motion!]

# Search for labels by description
label_search(
query: String
limit: Int = 20
): [LabelSearchResult!]

# Get a job by job ID
job(job_id: String): Job

# List jobs, optionally filtered by method
jobs(method: String): [Job!]
}

Mutations

type Mutation {
# Generate a motion from text prompt
create_text_to_motion(
character_id: String!
foot_ik: Boolean = true
model: String
prompt: String!
): CreateTextToMotion!

# Generate a motion from a video file
create_video_to_motion(
character_id: String!
file: Upload!
motion_name: String!
): CreateVideoToMotion!

# Upload a new character
create_character(
file: Upload!
name: String!
org_id: String
root: String
root_rotation: [Float]
root_translation: [Float]
use_prerotations: Boolean = true
): CreateCharacter!

# Stitch two motions together
create_stitched_motion(
character_id: String!
duration: Float
leading_motion_id: String!
trailing_motion_id: String!
): CreateStitchedMotion!

# Create a motion from a GLTF string
create_motion_from_gltf(
character_id: String!
desired_motion_name: String
gltf: String!
motion_id: String!
): CreateMotionFromGltf!

# Trim and optionally loop a motion
trim_and_loop_motion(
desired_motion_name: String
end_pct: Float!
loop: Boolean!
loop_root_motion: Boolean!
orig_motion_id: String!
start_pct: Float!
): TrimAndLoopMotion!

# Rate a motion or label
rate_motion(
label_id: String
motion_id: String!
score: Int!
): RateMotion!

# Update a motion's name or deletion status
update_motion(
deleted: Boolean
motion_id: String!
name: String
): UpdateMotion!
}

Example queries

Get motion details

query GetMotion($id: String!) {
motion(id: $id) {
id
name
created
updated
org_id
priority
tags
motion_viewer
training
assets {
id
filename
}
labels {
id
description
start
end
}
rating {
score
user_id
}
}
}

List motions

query ListMotions {
motions(methods: ["TextToMotion"]) {
id
name
org_id
created
assets {
filename
}
}
}

Generate motion from text (text-to-motion)

mutation GenerateTextMotion {
create_text_to_motion(
character_id: "CHARACTER_ID"
prompt: "walk casually"
foot_ik: true
model: "text-to-motion"
) {
ok
job_id
motion {
id
name
}
}
}

Upload a character

mutation UploadCharacter($file: Upload!) {
create_character(
file: $file
name: "My Character"
org_id: "ORG_ID"
) {
ok
character_id
skeleton_id
motion_id
}
}

Download a motion as FBX or GLB

All motion files are available via the following endpoint:

https://uthana.com/motion/file/motion_viewer/<character-id>/<motion-id>/<type>/<character-id>-<motion-id>.<type>
  • app_id: The application context (always use motion_viewer)
  • character_id: The character's ID
  • motion_id: The motion's ID
  • type: The file type/format (fbx, glb)

Rate limits

Rate limits are enforced on a per-organization basis. Reach out to the Uthana team to discuss your needs.

Error handling

GraphQL errors are returned in the errors array:

{
"errors": [
{
"message": "Rate limit exceeded",
"extensions": {
"code": "RATE_LIMIT_EXCEEDED",
"resetAt": "2025-01-01T00:00:00Z"
}
}
]
}