NAV Navbar
JavaScript curl
  • Introduction
  • Response format
  • Including related resources
  • Sparse attributes
  • Pagination
  • Common query parameters
  • Errors
  • Introduction

    The Sharetribe Flex API consists of three individual APIs:

    All three 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:

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

    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": 1014,
        "totalPages": 21,
        "page": 2,
        "perPage": 50
      }
    }
    

    Query API endpoints that return multiple resources (such as /listings/query) 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.

    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.
    totalPages Total number of pages, given the page size (perPage).
    page The number of the page returned in the response.
    perPage The number of resources returned per page. Affects the totalPages.

    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.

    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 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.
    500 Internal server error. The API failed to process the request due to unexpected error.