Introduction

The Sharetribe API consists of several individual APIs:

• Marketplace API
• Integration API
• Authentication API
• Asset Delivery API

All these are HTTP APIs. The Marketplace API and the Integration API support both JSON and Transit formats. The Authentication API is used to obtain access tokens for use with the other APIs and is based on OAuth2. The easiest way the access all three APIs is to use our JavaScript SDKs.

The Marketplace API facilitates all the core interactions that end users have with the marketplace. The Integration API, on the other hand, provides deeper access to all marketplace data, facilitating building more complex integrations. For more detailed description of the different APIs, see also this article.

The Marketplace and Integration APIs work in the same way regarding the following:

• Response format
• Including related resources
• Sparse attributes
• Pagination
• Common query parameters related to the above mechanisms

The Asset Delivery API facilitates content delivery for marketplace assets.

In addition to this API reference documentation it is also advised to familiarize oneself with the following two docs articles to fully grasp the context in which the Sharetribe APIs operate:

• Concepts - The key concepts that are used in all communication regarding Sharetribe
• Features - The main features provided by Sharetribe

You can also use Postman to test our APIs:

Response format

Example basic response

{
  "data": {
    "id": "3c073fae-6172-4e75-8b92-f560d58cd47c",
    "type": "user",
    "attributes": {
      "banned": false,
      "deleted": false,
      "profile": {
        "displayName": "Joe D",
        "abbreviatedName": "JD",
        "bio": "Hello, I'm Joe."
      }
    }
  }
}

An API resource is always identified by and id and type. The id is always a UUID. The API reference describes each type and it's attributes in more detail.

Each resource type has its own set of attributes. These attributes are returned by default for API read requests (GET). Responses for API write requests (POST) only return a resource reference (an object with only id and type keys). Clients may request write requests to return the full attribute set by adding expand=true as query parameter. Additionally, clients can control the set of returned attributes for each resource type in the API responses via sparse attribute queries. Using sparse attributes is highly recommended because it allows for smaller and faster API responses.

Each requested attribute (whether because it is in the default set of attributes, or because it was explicitly requested) is present in the API response. If data for that attribute did not exist, the value is populated with a default null value.

A resource may have a set of relationships to other resources. For instance, listing has author relationship to a user resource. Clients may request that the API also returns data about related resources in the response.

Responses may contain metadata in the meta top-level response key. The meta is an object that may contain information about the response, such as pagination information.

Including related resources

Example response with included resources. listing resource with included: author, author.profileImage and images relationships:

{
  "data": {
    "id": "c6ff7190-bdf7-47a0-8a2b-e3136e74334f",
    "type": "listing",
    "attributes": {
      "description": "7-speed Hybrid",
      "closed": false,
      "deleted": false,
      "geolocation": {
        "lat": 40.64542,
        "lng": -74.08508
      },
      "createdAt": "2018-03-23T08:40:24.443Z",
      "state": "published",
      "title": "Peugeot eT101",
      "publicData": {},
      "price": {
        "amount": 1590,
        "currency": "USD"
      }
    },
    "relationships": {
      "author": {
        "data": {"id": "3c073fae-6172-4e75-8b92-f560d58cd47c", "type": "user"}
      },
      "images": {
        "data": [
          {"id": "6a177221-247e-42a9-9cca-403238b86d7c", "type": "image"},
          {"id": "f8afadaa-dd4f-4536-b9a7-b405834dc25d", "type": "image"}
        ]
      }
    }
  },
  "included": [
    {
      "id": "3c073fae-6172-4e75-8b92-f560d58cd47c",
      "type": "user",
      "attributes": {
        "banned": false,
        "profile": {
          "displayName": "Joe D",
          "abbreviatedName": "JD",
          "bio": "Hello, I'm Joe."
        }
      },
      "relationships": {
        "profileImage": {
          "data": {"id": "a7c06f9d-5c69-4b70-adce-6f39639177b5", "type": "image"}
        }
      }
    },
    {
      "id": "f8afadaa-dd4f-4536-b9a7-b405834dc25d",
      "type": "image",
      "attributes": {
        "variants": {
          "default": {
            "width": 720,
            "height": 540,
            "url": "https://www.example.com/image/f8afadaa-dd4f-4536-b9a7-b405834dc25d"
          }
        }
      }
    },
    {
      "id": "6a177221-247e-42a9-9cca-403238b86d7c",
      "type": "image",
      "attributes": {
        "variants": {
          "default": {
            "width": 720,
            "height": 540,
            "url": "https://www.example.com/image/6a177221-247e-42a9-9cca-403238b86d7c"
          }
        }
      }
    },
    {
      "id": "a7c06f9d-5c69-4b70-adce-6f39639177b5",
      "type": "image",
      "attributes": {
        "variants": {
          "default": {
            "width": 720,
            "height": 540,
            "url": "https://www.example.com/image/a7c06f9d-5c69-4b70-adce-6f39639177b5"
          }
        }
      }
    }
  ]
}

Most resource types have relationships to other resources. When a given resource type has related resources, clients may request that the related resources be included in API responses for that given resource type.

Including related resources is done by adding include query parameter to the API request. The value is a comma-separated list of relationships to include. For instance include=marketplace,author requests that the marketplace and author relationships be included in API responses that return a listing resource.

When a relationship is included, the main resource(s) contain relationships objects and the overall response JSON object contains a top-level key included.

The relationships object has keys corresponding to the requested relationships for the resource and the values have data The data is a resource reference (when the relationship is to single resource) or an array of resource references (when the relationship is to multiple resources).

The value of included is an array with one or more included resource objects. All included resources are in that array and can be identified by their id and type.

Including nested relationships (relationships of the related resources themselves - e.g. listing > author > marketplace) is generally not supported, unless explicitly documented for each resource type. For instance, requesting author.profileImage is supported for the listing resources. Supported nested relationships take the form of dot-separated names of relationships. In the example case of author.profileImage for a listing, the the author relationship of the listing and the profileImage relationship of the user, who is referred to by the author relationship are both present in the response (see the example response).

Limiting number of included resources

When a resource has a relationship that refers to multiple resources (e.g. listing's images), by default the API returns up to 100 of the related resources.

API clients can limit included resources per relationship by using limit.RELATIONSHIP_NAME query parameter. E.g. use limit.images=2 to request only 2 images per listing in a /listings/query query. Multiple limit parameters may be used when multiple relationships need to be limited.

For limiting the number of main resources returned by a read request, see Pagination.

Sparse attributes

Example request

$ curl 'https://flex-api.sharetribe.com/v1/api/listings/show?id=c6ff7190-bdf7-47a0-8a2b-e3136e74334f&fields.listing=title,description&fields.author=profile.abbreviatedName' \
    -H 'Accept: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN'

var listingId = new UUID("c6ff7190-bdf7-47a0-8a2b-e3136e74334f");
sdk.ownListings.show({
  id: listingId,
  "fields.listing": ["title", "description"],
  "fields.author": ["profile.abbreviatedName"]
}).then(res => {
  // res.data contains the response data
});

API clients can request that an endpoint returns only specific attributes in the response on a per-type basis by including a fields.RESOURCE_TYPE parameter.

The value of the fields.RESOURCE_TYPE parameter is a comma-separated list that refers to the name(s) of the attributes to be returned. The field name can be nested. In this case, the nested path parts must be separated by a dot.

If a client requests a restricted set of fields for a given resource type, an endpoint does not include additional fields in resource objects of that type in its response. If fields are not specified for a given resource type, a default set of resource fields is returned.

Some resource types may have attributes that are not returned by the API by default. These attributes can be fetched only by explicitly specifing them in the fields.RESOURCE_TYPE parameter. For example, only a default variant for an image is returned by default.

Pagination

Example response for query /v1/api/listings/query?perPage=50,page=2

{
  "data": [
    {
      "id": "c6ff7190-bdf7-47a0-8a2b-e3136e74334f",
      "type": "listing",
      "attributes": {
        "description": "7-speed Hybrid",
        "closed": false,
        "deleted": false,
        "geolocation": {
          "lat": 40.64542,
          "lng": -74.08508
        },
        "createdAt": "2018-03-23T08:40:24.443Z",
        "state": "published",
        "title": "Peugeot eT101",
        "publicData": {
          "address": {
            "city": "New York",
            "country": "USA",
            "state": "NY",
            "street": "230 Hamilton Ave"
          },
          "category": "road",
          "gears": 22,
          "rules": "This is a nice, bike! Please, be careful with it."
        },
        "price": {
          "amount": 1590,
          "currency": "USD"
        }
      }
    },
    {...},
    {...}
  ],
  "meta": {
    "totalItems": 10200,
    "totalPages": 204,
    "page": 2,
    "paginationLimit": 200,
    "perPage": 50
  }
}

Query API endpoints that return multiple resources (such as /listings/query) generally support and use pagination. The default page size is 100. Clients can request additional results or control page size with the following query parameters:

Parameter	Description
page	(positive integer) The page number.
perPage	(positive integer) Number of resources to return per page. Must be between 1 and 100.

Under some conditions, some API endpoints do not support pagination and instead return up to a certain number of results. Those conditions are documented separately for each API endpoint.

Paginated responses contain pagination information in the meta top-level response key. The following attributes are returned:

Attribute	Description
totalItems	Total number of resources that matched the query. May be null if the corresponding API endpoint does not support pagination under certain conditions.
totalPages	Total number of pages, given the page size (perPage). May be null if the corresponding API endpoint does not support pagination under certain conditions.
page	The number of the page returned in the response.
perPage	The number of resources returned per page. Affects the totalPages.
paginationLimit	The last page that can be requested with the given query and the data stored at the request time.
paginationUnsupported	Set to true in case the API endpoint does not support pagination with the current set of query parameters.

Common query parameters

The following list contains common query parameters that are supported by all or most API endpoints.

Parameter	Description
include	(string) Comma-separated list of relationships to be returned by the API. All API endpoints support this parameter.
page	(positive integer) Page number for read (also known as query) endpoints that return multiple resources.
perPage	(positive integer) Number of resources to be returned per page for read endpoints that return multiple resources.
expand	(boolean) Indicate whether the API write endpoint (also known as command) should return full resource (with attributes) or just a resource reference. Only applies to write API endpoints.
fields.*	(string) Comma-separated list of attributes for sparse attribute queries. All API endpoints support these parameters.
limit.*	(positive integer) Number of included resources to return per relationship. All API endpoints support these parameters.

Rate limits

The Marketplace API and the Integration API have various safeguards to protect against bursts of traffic in order to improve the API stability. These include:

• Rate limiters that restrict the number of requests that are accepted by the APIs in a given period of time.
• Concurrency limiters that restrict the number of requests that the API is processing at any given time.

See the individual API reference for details:

• Rate limits in the Marketplace API
• Rate limits in the Integration API

See this article for advice on how to handle these limits gracefully.

Errors

Example error response

{
  "errors": [
    {
      "id": "2a67748f-33d4-4293-8323-5a1d256e83b8",
      "status": 400,
      "code": "validation-invalid-value",
      "title": "Invalid value",
      "details": "lat must be a valid number for a latitude.",
      "source": {
        "path": ["location", "lat"],
        "type": "body"
      }
    },
    {
      "id": "2a67748f-33d4-4293-8323-5a1d256e83b7",
      "status": 400,
      "code": "validation-missing-key",
      "title": "Missing required key.",
      "source": {
        "path": ["title"],
        "type": "body"
      }
    },
    {
      "id": "2a67748f-33d4-4293-8323-5a1d256e83b9",
      "status": 400,
      "code": "validation-disallowed-key",
      "title": "Disallowed key.",
      "source": {
        "path": ["price", "sum"],
        "type": "body"
      }
    },
    {
      "id": "2a67748f-33d4-4293-8323-5a1d256e83ba",
      "status": 400,
      "code": "validation-disallowed-key",
      "title": "Disallowed key.",
      "source": {
        "path": ["title"],
        "type": "query"
      }
    }
  ]
}

In case of an error, the API returns a top-level key errors in the response with an array of one or more error objects and the HTTP response will have appropriate 4xx or 5xx status code. Responses with 5xx status codes are not guaranteed to have a valid JSON or Transit body.

Error format

Attribute	Description
id	(uuid) The error ID. This is unique ID for each instance of an error.
status	(number) HTTP status code for the error.
code	(string) Error code. Clients can use the error code to determine what the error was. See the list of error codes.
title	(string) Human readable error title. The title is always the same for a given error code.
details	(string, optional) Human readable explanation of the error. This is an optional attribute and, when present, is intended to be used to aid API client development and debugging. API clients should not reply on the presence or the contents of this attribute.
source	(object, optional) Indicates the request parameter (in query string or body) that caused the error, when possible.
source.path	(array) Array of strings, representing the (nested) path to a key in the request body or the name of the query parameter that the error is attributed to.
source.type	(string) Indicates whether the path represents a body or query parameter.

HTTP status codes

The following table describes some commonly used HTTP status codes.

HTTP status code	Description
400	Bad request. Typically used to indicate that the request contained invalid query or body parameter or syntax.
401	Unauthorized. The API request was made with invalid or expired access token. The client must obtain a valid and fresh access token via the Authentication API.
402	Payment failed. Used to indicate error during payment processing. See Transactions.
403	Forbidden. The authenticated or anonymous user does not have access to the requested resource or API endpoint.
404	Not found. Returned by query endpoints when the requested resource is not found. Note that queries that return multiple resources DO NOT return a 404 error when no resource matches the query parameters. Instead, they return response with empty data array. See Response format.
409	Conflict. The command can not be completed. This is commonly caused by a missing resource, which is required by the command, a resource in an unexpected state, logic error in the request, etc.
429	Too many requests. The request is rejected due to either a request rate or concurrency limit. The response may not have a body.
500	Internal server error. The API failed to process the request due to unexpected error. The response may not contain a valid JSON or Transit body.