---
title: "Storage API"
url: "https://developers.rest.rodeo/apis/storage/versions/8415f51a-292b-4046-b795-bc13ea7a48cf"
---

# Storage API

OpenAPI specification document.

```json
{"openapi":"3.0.3","info":{"title":"Storage API","description":"Manages buckets and the JSON objects stored in them. Each object is a single JSON `data` value whose stringified content can be at most 1MB. The billing profile is a subscription with a quota entitlement. Basic allows up to 10 buckets and 10,000 objects (up to 10GB total). Premium allows unlimited buckets and 100,000 objects (up to 100GB total). Max allows unlimited buckets and 1,000,000 objects (up to 1TB total). Buckets must be created before adding objects, and must be empty before they can be deleted.","version":"1.0.0"},"servers":[{"url":"https://api.rest.rodeo/storage/api/v1","description":"Production"}],"security":[{"bearerAuth":[]}],"paths":{"/buckets":{"get":{"operationId":"listBuckets","summary":"/buckets","description":"Lists every bucket.","responses":{"200":{"description":"All buckets","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BucketsList"},"examples":{"buckets":{"value":{"buckets":[{"id":"5a1c2c7e-0c6f-4e58-b3e3-c6a2d1f1a9e4","name":"project-files"}]}}}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createBucket","summary":"/buckets","description":"Creates a bucket. Returns 402 when the subscription tier's bucket quota is already reached.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BucketRequest"},"examples":{"create":{"value":{"name":"project-files"}}}}}},"responses":{"201":{"description":"The created bucket","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Bucket"},"examples":{"bucket":{"value":{"id":"5a1c2c7e-0c6f-4e58-b3e3-c6a2d1f1a9e4","name":"project-files"}}}}}},"400":{"description":"Invalid JSON body or invalid `name`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Bucket quota exceeded for the subscription tier","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/buckets/{bucketId}":{"get":{"operationId":"getBucket","summary":"/buckets/{bucketId}","description":"Returns a single bucket by id.","parameters":[{"$ref":"#/components/parameters/BucketId"}],"responses":{"200":{"description":"The bucket","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Bucket"},"examples":{"bucket":{"value":{"id":"5a1c2c7e-0c6f-4e58-b3e3-c6a2d1f1a9e4","name":"project-files"}}}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No bucket with this id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"operationId":"updateBucket","summary":"/buckets/{bucketId}","description":"Replaces the bucket's name.","parameters":[{"$ref":"#/components/parameters/BucketId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BucketRequest"},"examples":{"update":{"value":{"name":"archived-files"}}}}}},"responses":{"200":{"description":"The updated bucket","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Bucket"},"examples":{"bucket":{"value":{"id":"5a1c2c7e-0c6f-4e58-b3e3-c6a2d1f1a9e4","name":"archived-files"}}}}}},"400":{"description":"Invalid JSON body or invalid `name`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No bucket with this id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteBucket","summary":"/buckets/{bucketId}","description":"Deletes the bucket. Rejected with 409 while the bucket still contains objects.","parameters":[{"$ref":"#/components/parameters/BucketId"}],"responses":{"204":{"description":"The bucket was deleted"},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No bucket with this id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The bucket is not empty","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/buckets/{bucketId}/objects":{"get":{"operationId":"listObjects","summary":"/buckets/{bucketId}/objects","description":"Lists every object in the bucket.","parameters":[{"$ref":"#/components/parameters/BucketId"}],"responses":{"200":{"description":"All objects in the bucket","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ObjectsList"},"examples":{"objects":{"value":{"objects":[{"id":"c7f2b6de-4b1a-4e0f-9b0d-1f6e4c8a2b3c","data":{"name":"manifest.json","size":1024}}]}}}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No bucket with this id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createObject","summary":"/buckets/{bucketId}/objects","description":"Creates an object in the bucket. Returns 402 when the subscription tier's total object quota is already reached, and 413 when the stringified `data` exceeds 1MB.","parameters":[{"$ref":"#/components/parameters/BucketId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ObjectRequest"},"examples":{"create":{"value":{"data":{"name":"manifest.json","size":1024}}}}}}},"responses":{"201":{"description":"The created object","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoredObject"},"examples":{"object":{"value":{"id":"c7f2b6de-4b1a-4e0f-9b0d-1f6e4c8a2b3c","data":{"name":"manifest.json","size":1024}}}}}}},"400":{"description":"Invalid JSON body or missing `data`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Object quota exceeded for the subscription tier","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No bucket with this id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The stringified `data` exceeds 1MB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/buckets/{bucketId}/objects/{objectId}":{"get":{"operationId":"getObject","summary":"/buckets/{bucketId}/objects/{objectId}","description":"Returns a single object by id.","parameters":[{"$ref":"#/components/parameters/BucketId"},{"$ref":"#/components/parameters/ObjectId"}],"responses":{"200":{"description":"The object","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoredObject"},"examples":{"object":{"value":{"id":"c7f2b6de-4b1a-4e0f-9b0d-1f6e4c8a2b3c","data":{"name":"manifest.json","size":1024}}}}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No bucket or object with these ids","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"operationId":"updateObject","summary":"/buckets/{bucketId}/objects/{objectId}","description":"Replaces the object's `data`. Returns 413 when the stringified `data` exceeds 1MB.","parameters":[{"$ref":"#/components/parameters/BucketId"},{"$ref":"#/components/parameters/ObjectId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ObjectRequest"},"examples":{"update":{"value":{"data":{"name":"manifest.json","size":2048}}}}}}},"responses":{"200":{"description":"The updated object","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoredObject"},"examples":{"object":{"value":{"id":"c7f2b6de-4b1a-4e0f-9b0d-1f6e4c8a2b3c","data":{"name":"manifest.json","size":2048}}}}}}},"400":{"description":"Invalid JSON body or missing `data`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No bucket or object with these ids","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The stringified `data` exceeds 1MB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteObject","summary":"/buckets/{bucketId}/objects/{objectId}","description":"Deletes the object.","parameters":[{"$ref":"#/components/parameters/BucketId"},{"$ref":"#/components/parameters/ObjectId"}],"responses":{"204":{"description":"The object was deleted"},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No bucket or object with these ids","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"parameters":{"BucketId":{"name":"bucketId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The bucket id."},"ObjectId":{"name":"objectId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The object id."}},"schemas":{"Bucket":{"type":"object","required":["id","name"],"additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid","description":"The bucket id."},"name":{"type":"string","description":"The bucket name.","maxLength":256}}},"BucketRequest":{"type":"object","required":["name"],"additionalProperties":false,"properties":{"name":{"type":"string","description":"The bucket name.","maxLength":256,"minLength":1}}},"BucketsList":{"type":"object","required":["buckets"],"additionalProperties":false,"properties":{"buckets":{"type":"array","items":{"$ref":"#/components/schemas/Bucket"}}}},"StoredObject":{"type":"object","required":["id","data"],"properties":{"id":{"type":"string","format":"uuid","description":"The object id."},"data":{"description":"The stored JSON value. May be any JSON type and any depth, as long as its stringified content does not exceed 1MB."}}},"ObjectRequest":{"type":"object","required":["data"],"additionalProperties":false,"properties":{"data":{"description":"The JSON value to store. May be any JSON type and any depth, as long as its stringified content does not exceed 1MB."}}},"ObjectsList":{"type":"object","required":["objects"],"additionalProperties":false,"properties":{"objects":{"type":"array","items":{"$ref":"#/components/schemas/StoredObject"}}}},"Error":{"type":"object","required":["error"],"additionalProperties":false,"properties":{"error":{"type":"string"}}}}}}
```