APIs

Management API

The back-office API for administrative integrations — configure, launch, and operate your commercial logic on Basta.

The Management API is intended for back-office systems and administrative integrations. It enables you to configure, launch, and operate your commercial logic on Basta.

Common responsibilities

Creating and updating auctions
Managing inventory and item metadata
Defining pricing, bidding rules, and time-based conditions
Issuing bidder tokens for secure user access to the Client API

Authentication

All requests to the Management API must be authenticated with headers. See Getting Started for details on obtaining your API credentials.

Required headers

JSON

{
  "x-account-id": "YOUR_ACCOUNT_ID",
  "x-api-key": "YOUR_API_KEY"
}

Endpoints

GraphQL Explorer: management-api.basta.app/graphql

Explore available GraphQL endpoints in the interactive playground.

Example: creating an auction

GraphQL

mutation CreateSale {
  createSale(input: {
    title: "Summer Auction 2024"
    description: "Fine art and collectibles"
    startDate: "2024-07-01T10:00:00Z"
    endDate: "2024-07-15T20:00:00Z"
  }) {
    id
    title
    status
  }
}

Example: issuing a bidder token

GraphQL

mutation CreateBidderToken {
  createBidderToken(input: {
    userId: "user-123"
    ttl: 3600
  }) {
    token
    expiresAt
  }
}

This token can then be used by your users to authenticate with the Client API.

Code examples

Node.js/TypeScript

TypeScript

import fetch from 'node-fetch';

const MANAGEMENT_API_URL = 'https://management-api.basta.app/graphql';

async function createSale() {
  const response = await fetch(MANAGEMENT_API_URL, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-account-id': process.env.BASTA_ACCOUNT_ID,
      'x-api-key': process.env.BASTA_API_KEY
    },
    body: JSON.stringify({
      query: `
        mutation CreateSale($input: CreateSaleInput!) {
          createSale(input: $input) {
            id
            title
            status
          }
        }
      `,
      variables: {
        input: {
          title: 'Summer Auction 2024',
          description: 'Fine art and collectibles',
          startDate: '2024-07-01T10:00:00Z',
          endDate: '2024-07-15T20:00:00Z'
        }
      }
    })
  });

  const result = await response.json();
  return result.data.createSale;
}

Ruby

require 'net/http'
require 'json'

class BastaManagementAPI
  API_URL = 'https://management-api.basta.app/graphql'

  def initialize(account_id, api_key)
    @account_id = account_id
    @api_key = api_key
  end

  def create_sale(title:, description:, start_date:, end_date:)
    query = <<~GRAPHQL
      mutation CreateSale($input: CreateSaleInput!) {
        createSale(input: $input) {
          id
          title
          status
        }
      }
    GRAPHQL

    variables = {
      input: {
        title: title,
        description: description,
        startDate: start_date,
        endDate: end_date
      }
    }

    execute_query(query, variables)
  end

  private

  def execute_query(query, variables = {})
    uri = URI(API_URL)
    request = Net::HTTP::Post.new(uri)
    request['Content-Type'] = 'application/json'
    request['x-account-id'] = @account_id
    request['x-api-key'] = @api_key
    request.body = JSON.generate({
      query: query,
      variables: variables
    })

    response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
      http.request(request)
    end

    JSON.parse(response.body)
  end
end

# Usage
api = BastaManagementAPI.new(
  ENV['BASTA_ACCOUNT_ID'],
  ENV['BASTA_API_KEY']
)

result = api.create_sale(
  title: 'Summer Auction 2024',
  description: 'Fine art and collectibles',
  start_date: '2024-07-01T10:00:00Z',
  end_date: '2024-07-15T20:00:00Z'
)

Best practices

Secure your credentials: Never expose your API key in client-side code
Use environment variables: Store credentials in environment variables
Error handling: Always handle GraphQL errors appropriately
Rate limiting: Respect rate limits to ensure smooth operations
Idempotency: Use idempotency keys for critical mutations