Introduction
The Sharetribe API consists of several individual APIs:
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
andimages
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:
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. |