Noroff API Documentation

Some of these are authenticated endpoints. You can visit authentication to register an account.

These endpoints allow you to create, read, update, delete listings. Listings are the main content of an auction house. They are created by profiles and can be bid on by other profiles.

These endpoints support pagination and sorting. Read more about these features here.

The Listing model

Prop	Type	Default
`id`	`string`	-
`title`	`string`	-
`description`	`string`	-
`tags`	`Array<string>`	-
`media`	`Array<object>`	-
`created`	`string`	-
`updated`	`string`	-
`endsAt`	`string`	-
`_count`	`object`	-

Query parameters

Not all of the properties of a listing are returned by default. You can use the following optional query parameters to include additional properties in the response.

Prop	Type	Default
`_seller`	`boolean`	`false`
`_bids`	`boolean`	`false`

Example with all optional query parameters

{
  "data": {
    "id": "string",
    "title": "string",
    "description": "string",
    "tags": ["string"],
    "media": [
      {
        "url": "https://url.com/image.jpg",
        "alt": "string"
      }
    ],
    "created": "2020-01-01T00:00:00.000Z",
    "updated": "2020-01-01T00:00:00.000Z",
    "endsAt": "2020-01-01T00:00:00.000Z",
    "seller": {
      "name": "string",
      "email": "user@example.com",
      "bio": "string",
      "avatar": {
        "url": "https://url.com/image.jpg",
        "alt": "string"
      },
      "banner": {
        "url": "https://url.com/image.jpg",
        "alt": "string"
      },
      "wins": ["string"]
    },
    "bids": [
      {
        "id": "string",
        "amount": 0,
        "bidder": {
          "name": "string",
          "email": "user@example.com",
          "bio": "string",
          "avatar": {
            "url": "https://url.com/image.jpg",
            "alt": "string"
          },
          "banner": {
            "url": "https://url.com/image.jpg",
            "alt": "string"
          }
        },
        "created": "2020-01-01T00:00:00.000Z"
      }
    ],
    "_count": {
      "bids": 0
    }
  },
  "meta": {}
}

Filtering

You can filter for active listings by using the _active query flag.

You can filter based on an entry in the tags array by using the _tag query flag. You may only filter by one tag at a time.

Prop	Type	Default
`_tag`	`string`	-
`_active`	`boolean`	-

An example query filtering for active listings with the my_tag tag.

GET/auction/listings?_tag=my_tag&_active=true

All listings

This endpoint does not require authentication.

GET/auction/listings

Retrieve all listings.

If you want to get all listings by a specific profile, you can use the listings by profile endpoint.

Response

{
  "data": [
    {
      "id": "string",
      "title": "string",
      "description": "string",
      "tags": ["string"],
      "media": [
        {
          "url": "https://url.com/image.jpg",
          "alt": "string"
        }
      ],
      "created": "2020-01-01T00:00:00.000Z",
      "updated": "2020-01-01T00:00:00.000Z",
      "endsAt": "2020-01-01T00:00:00.000Z",
      "_count": {
        "bids": 0
      }
    },
    {
      "id": "string",
      "title": "string",
      "description": "string",
      "tags": ["string"],
      "media": [
        {
          "url": "https://url.com/image.jpg",
          "alt": "string"
        }
      ],
      "created": "2020-01-01T00:00:00.000Z",
      "updated": "2020-01-01T00:00:00.000Z",
      "endsAt": "2020-01-01T00:00:00.000Z",
      "_count": {
        "bids": 0
      }
    }
    // ...
  ],
  "meta": {
    "isFirstPage": true,
    "isLastPage": true,
    "currentPage": 1,
    "previousPage": null,
    "nextPage": null,
    "pageCount": 1,
    "totalCount": 2
  }
}

Single listing

This endpoint does not require authentication.

GET/auction/listings/<id>

Retrieve a single listing by its id.

Use the _seller, and/or _bids flags to get more data from this request.

Response

{
  "data": {
    "id": "string",
    "title": "string",
    "description": "string",
    "tags": ["string"],
    "media": [
      {
        "url": "https://url.com/image.jpg",
        "alt": "string"
      }
    ],
    "created": "2020-01-01T00:00:00.000Z",
    "updated": "2020-01-01T00:00:00.000Z",
    "endsAt": "2020-01-01T00:00:00.000Z",
    "_count": {
      "bids": 0
    }
  },
  "meta": {}
}

Create listing

POST/auction/listings

Create a new listing. The title and endsAt properties are required, but we recommend at least including the description and media properties as well.

Please note that each of the url properties in the media array must be a fully formed URL that links to a live and publicly accessible image. The API will check the provided URLs and if any cannot be accessed publicly you will receive a 400 Bad Request error response.

Request

{
  "title": "string", // Required
  "description": "string", // Optional
  "tags": ["string"], // Optional
  "media": [
    {
      "url": "https://url.com/image.jpg",
      "alt": "string"
    }
  ], // Optional
  "endsAt": "2020-01-01T00:00:00.000Z" // Required - Instance of new Date()
}

Response

{
  "data": {
    "id": "string",
    "title": "string",
    "description": "string",
    "tags": ["string"],
    "media": [
      {
        "url": "https://url.com/image.jpg",
        "alt": "string"
      }
    ],
    "created": "2020-01-01T00:00:00.000Z",
    "updated": "2020-01-01T00:00:00.000Z",
    "endsAt": "2020-01-01T00:00:00.000Z",
    "_count": {
      "bids": 0
    }
  },
  "meta": {}
}

Update listing

PUT/auction/listings/<id>

Update a listing.

Request

{
  "title": "string", // Optional
  "description": "string", // Optional
  "tags": ["string"], // Optional
  "media": [
    {
      "url": "https://url.com/image.jpg",
      "alt": "string"
    }
  ] // Optional
}

Delete listing

DELETE/auction/listings/<id>

Delete a listing.

Returns an empty 204 No Content response on success.

Bid on listing

POST/auction/listings/<id>/bids

Create new bid on a listing.

When a listing ends, the winning bid amount will be transferred to the seller's credits. All losing bids will be refunded to its original bidder's credits.

Request

{
  "amount": 0 // Required
}

Response

{
  "data": {
    "id": "string",
    "title": "string",
    "description": "string",
    "tags": ["string"],
    "media": [
      {
        "url": "https://url.com/image.jpg",
        "alt": "string"
      }
    ],
    "created": "2020-01-01T00:00:00.000Z",
    "updated": "2020-01-01T00:00:00.000Z",
    "endsAt": "2020-01-01T00:00:00.000Z",
    "_count": {
      "bids": 0
    }
  },
  "meta": {}
}

Search listings

GET/auction/listings/search?q=<query>

Search for listings by their title or description properties.

Listings

On this page