craigslist-api

client  = Craigslist::API.new(email: ..., password: ..., account_id: ...)
results = client.post(postings)          # RSS under the hood
client.posting(results.posting_ids.first).price = 4200   # JSON under the hood

gem "craigslist-api"

require "craigslist/api"

client = Craigslist::API.new(
  email:      "you@example.com",
  password:   ENV.fetch("CRAIGSLIST_PASSWORD"),
  account_id: 1234
)

posting = Craigslist::API::Posting.new(
  key:         "listing-1",              # your own identifier for this posting
  title:       "1998 Toyota Hilux",
  description: "Runs great. Highway miles.",
  category:    "ctd",                    # cars & trucks - by dealer
  area:        "sfo",
  price:       4500,
  reply_email: "sales@example.com",
  location:    {postal: "94110"}
)

# Dry run first. This sends the identical document that #post would.
check = client.validate(posting)
abort check.failed.map(&:explanation).join("\n") if check.any_failures?

results = client.post(posting)
results.posting_ids  #=> ["7123456780"]

results = client.post(postings)

results.all_successful?   #=> false
results.successful        #=> [Result, ...]
results.failed            #=> [Result, ...]
results.posting_ids       #=> ids of postings that were created
results.upload_id         #=> craigslist's id for the whole batch
results["listing-1"]      #=> the Result for the key you submitted

results.failed.each do |result|
  warn "#{result.key}: #{result.status} — #{result.explanation}"
end

puts results.raw    # the RSS document exactly as craigslist sent it

results.warned.each do |result|
  warn "#{result.key} posted with warnings: #{result.warnings.join(", ")}"
end

Craigslist::API::Posting.new(
  key:                "listing-2",
  title:              "1BR in Chelsea",
  description:        "Sunny, quiet block.",
  category:           "apa",
  area:               "nyc",
  subarea:            "mnh",             # required where an area has subareas
  neighborhood:       "Chelsea",
  price:              4875,
  po_number:          "PO-094122",       # your own tracking reference
  reply_email:        "leasing@example.com",
  reply_privacy:      :anonymous,        # :none | :anonymous | :public
  other_contact_info: "212.555.1212",

  location: {
    postal: "10011", city: "New York", state: "NY",
    cross_street1: "23rd Street", cross_street2: "9th Avenue",
    latitude: 40.746492, longitude: -74.001326
  },

  housing_basics: {bedrooms: 1, bathrooms: 1, surface_area: 850,
                   housing_type: "apartment", laundry: "w/d in unit",
                   is_furnished: false},
  housing_terms:  {rent_period: "monthly", broker_fee: true},
  housing_pets:   {pets_cat: true, pets_dog: false},
  broker:         {company_name: "Sample & Associates", fee_disclosure: "One month"},

  images: ["photos/living-room.jpg", "photos/kitchen.jpg"]
)

Craigslist::API::Posting.new(key: "x", title: "", description: "b",
                             category: "", area: "sfo", location: {})
# => Craigslist::API::ValidationError:
#      title is required; category is required;
#      location requires :postal, or both :latitude and :longitude

images: [
  "photos/front.jpg",                                    # path
  Pathname("photos/side.jpg"),                           # Pathname
  File.open("photos/rear.jpg", "rb"),                    # any IO
  Craigslist::API::Image.from_base64(encoded, position: 5)
]

posting = client.posting("7123456780")

posting.status              #=> "active" | "deleted" | "expired" | "pending" | "removed"
posting.active?             #=> true

posting.body                #=> "The posting body"
posting.body = "New text"
posting.price = 4200
posting.remuneration = "$19.95/hr plus tips"   # jobs and gigs

posting.images              #=> [ImageInfo, ...]
posting.add_image("new.jpg")
posting.add_image("hero.jpg", insert_position: 0)
posting.reorder_images(%w[4:00202_x 4:00101_y])
posting.remove_image("4:00101_y")

posting.stats.total_views   #=> 1_284

posting.delete
posting.undelete

credit = client.credit
credit.remaining.to_s              #=> "3.00 USD"
credit.remaining.to_f              #=> 3.0

client.posting_blocks.each do |block|
  puts "#{block.area} #{block.product_class}: #{block.remaining_posts} left"
end

client.pricing(area: "sfo", category: "ofc").to_s   #=> "1000.00 USD"
client.billing.create_invoice                       #=> ["1234321"]

place = client.area_for_zip("02134")
place.area        #=> "bos"
place.subarea     #=> "gbs"
place.to_h        #=> {area: "bos", subarea: "gbs"}

stats = client.stats(start: "2026-01-01", stop: "2026-01-31")

stats.each do |posting|
  puts "#{posting.posting_id}: #{posting.total_views} views, #{posting.total_contact} contacts"
end

stats.first[:impressions]   #=> [[2026-01-01 00:00:00 UTC, 57], ...]

client.reference.area("sfo").subareas.map(&:abbreviation)  #=> ["sfc", "sby", ...]
client.reference.area("sfo").subareas?                     #=> true
client.reference.category("ctd").description               #=> "cars & trucks - by dealer"
client.reference.category("prk").unsupported?              #=> true

client.account_messages.each do |message|
  logger.info("craigslist: #{message["message"]}")
  client.account.acknowledge(message["messageId"])
end

begin
  client.posting("7123456780").body = "updated"
rescue Craigslist::API::APIError => e
  e.api_errors  #=> [{"code" => 0, "message" => "posting 7123456780 not found"}]
end

Craigslist::API.new(
  email:      "you@example.com",
  password:   ENV.fetch("CRAIGSLIST_PASSWORD"),
  account_id: 1234,

  timeout:      120,          # read timeout; generous, submissions can be large
  open_timeout: 15,
  logger:       Rails.logger, # logs request lines via Faraday
  adapter:      :net_http,    # any Faraday adapter
  scopes:       %w[bulkpost.posting bulkpost.account.billing],
  user_agent:   "my-app/1.0"
)

CLIENTS = accounts.to_h { |a| [a.id, Craigslist::API.new(**a.credentials)] }