Introduction

The WritersDB API gives you programmatic access to view and modify your data, including your titles, markets, and submissions. With this API, you are empowered to create a variety of tools and conveniences for yourself, such as:

Widgets for your desktop or a web-based dashboard
Automations via a platform like Zapier or n8n
Integrations with tools like Apple Shortcuts, Notion, Airtable, etc.
A complete app of your own devising

The API is available to Pro users. You can check your account status, and upgrade to Pro if you’re currently on the Free plan, on your Account page.

Continue to Authentication

Authentication

Creating an API Key

API keys are managed from your API Keys page, which is accessible from your Account page. A Pro account is required to create API keys.

When creating a key you assign a label (optional), choose an access level, and optionally set an expiration date. The raw key is displayed exactly once upon creation — copy and store it somewhere secure, as it cannot be retrieved again.

Access Levels

Read — permits GET requests that list and retrieve your data.
Read+Write — permits all read operations, plus POST requests that create or modify data.

Sending Your API Key

Each API request should include the Authorization header using the Bearer scheme:

Authorization: Bearer YOUR_API_KEY

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
	https://www.writersdb.com/api/titles/list

Error Responses

All error responses return a JSON object with an error message and a numeric code matching the HTTP status:

{"error": "Unauthorized", "code": 401}

Code	Meaning
400	Bad request — a required parameter is missing or has an invalid value
401	Unauthorized — API key is missing, invalid, or expired
403	Forbidden — a Pro account is required, or a read-only key was used on a write endpoint
404	Not found — the resource or endpoint does not exist
500	Server error — an unexpected internal error occurred

Back to Introduction

Continue to Titles

Titles

Get a list of titles

Endpoint

https://www.writersdb.com/api/titles/list

Returns all titles belonging to the authenticated user.

The Request

Request type: GET

Permission required: Read

The Response

Example response

[
  {
    "id": 1,
    "title": "The Last Signal",
    "ms_url": "https://docs.google.com/document/d/...",
    "notes": "Revised draft as of March 2025",
    "wordcount": 4200
  },
  {
    "id": 2,
    "title": "Salt and Stars",
    "ms_url": "",
    "notes": "",
    "wordcount": 2800
  }
]

Response fields

Field	Type	Description
id	integer	Unique identifier for the title
title	string	Title of the piece
ms_url	string	URL to the manuscript; may be empty
notes	string	User notes about the piece; may be empty
wordcount	integer	Most recent recorded word count; 0 if none has been recorded

Create a new title

Endpoint

https://www.writersdb.com/api/titles/create

Creates a new title for the authenticated user.

The Request

Request type: POST

Permission required: Read+Write

Example request body

title=The+Last+Signal&ms_url=https%3A%2F%2Fdocs.google.com%2F...&notes=First+draft

Request parameters

Parameter	Required	Type	Description
title	Yes	string	Title of the piece
ms_url	No	string	URL pointing to the manuscript file
notes	No	string	Free-form notes about the piece

The Response

Example response

{"id": 42}

Edit an existing title

Endpoint

https://www.writersdb.com/api/titles/edit/{id}

Updates fields on an existing title. Only fields included in the request are changed; omitted fields are left as-is.

The Request

Request type: POST

Permission required: Read+Write

Example request

POST https://www.writersdb.com/api/titles/edit/42

title=The+Last+Signal+%28Revised%29&notes=Second+draft+complete

Request parameters

Parameter	Required	Type	Description
title	No	string	New title text; omit to leave unchanged
ms_url	No	string	New manuscript URL; pass an empty string to clear
notes	No	string	New notes; pass an empty string to clear

The Response

Example response

{"success": true}

Set a word count

Endpoint

https://www.writersdb.com/api/titles/wordcount

Records the total word count for a given title on a given date. If a count already exists for that title and date it is updated; otherwise a new count is recorded.

The Request

Request type: POST

Permission required: Read+Write

Example request body

title_id=42&words=12500&date=2026-04-03

Request parameters

Parameter	Required	Type	Description
title_id	Yes	integer	ID of the title to update
words	Yes	integer	Total word count for this title as of the given date
date	No	date string (YYYY-MM-DD)	Date the word count applies to; defaults to today if omitted

The Response

Example response

{"success": true}

Back to Authentication

Continue to Markets

Markets

Get a list of markets

Endpoint

https://www.writersdb.com/api/markets/list

Returns all markets available to the authenticated user: markets they own plus markets they subscribe to.

The Request

Request type: GET

Permission required: Read

The Response

Example response

[
  {
    "id": 7,
    "name": "Clarkesworld",
    "responsetime": "6 weeks",
    "payrate": "8 cents/word",
    "maxwords": 16000,
    "tags": ["fiction", "sf"],
    "ownership": "subscribed"
  },
  {
    "id": 12,
    "name": "My Local Zine",
    "responsetime": null,
    "payrate": "",
    "maxwords": null,
    "tags": [],
    "ownership": "owned"
  }
]

Response fields

Field	Type	Description
id	integer	Unique identifier for the market
name	string	Name of the market
responsetime	string or null	Typical response time; freeform text (e.g., `"6 weeks"`, `"Quarterly"`, `"unknown"`); may be null
payrate	string	Pay rate description; may be empty
maxwords	integer or null	Maximum word count accepted
tags	array of strings	Category tags associated with the market
ownership	string	`owned` if created by the authenticated user; `subscribed` otherwise

Get market details

Endpoint

https://www.writersdb.com/api/markets/detail/{id}

Returns the full detail record for a single market.

The Request

Request type: GET

Permission required: Read

The Response

Example response

{
  "id": 7,
  "name": "Clarkesworld",
  "editor": "Neil Clarke",
  "web": "https://clarkesworldmagazine.com",
  "email": "submissions@clarkesworldmagazine.com",
  "emailsubs": "",
  "tel": "",
  "fax": "",
  "addr1": "",
  "addr2": "",
  "city": "",
  "state": "",
  "zip": "",
  "country": "",
  "responsetime": "6 weeks",
  "payrate": "8 cents/word",
  "maxwords": 16000,
  "simsubs": false,
  "multsubs": false,
  "reprints": false,
  "esubs": 2,
  "deadline": null,
  "entryfee": "",
  "shared": true,
  "tags": ["fiction", "sf"],
  "notes": "Science fiction and fantasy only.",
  "avg_response": 14,
  "ownership": "subscribed"
}

Response fields

Field	Type	Description
id	integer	Unique identifier
name	string	Market name
editor	string	Editor name; may be empty
web	string	Website URL; may be empty
email	string	Contact email; may be empty
emailsubs	string	Separate submission email address; may be empty
tel	string	Phone number; may be empty
fax	string	Fax number; may be empty
addr1	string	Mailing address line 1; may be empty
addr2	string	Mailing address line 2; may be empty
city	string	City; may be empty
state	string	State or province; may be empty
zip	string	Postal code; may be empty
country	string	Country; may be empty
responsetime	string or null	Typical response time; freeform text (e.g., `"6 weeks"`, `"Quarterly"`, `"unknown"`); may be null
payrate	string	Pay rate description; may be empty
maxwords	integer or null	Maximum word count accepted
simsubs	boolean	Whether simultaneous submissions to other markets are accepted
multsubs	boolean	Whether multiple submissions from the same author are accepted
reprints	boolean	Whether reprints are accepted
esubs	0, 1, or 2	Delivery method: 0 = Postal only, 1 = Postal AND e-mail, 2 = E-mail only
deadline	date string or null	Submission deadline in `YYYY-MM-DD` format, or null if open
entryfee	string	Entry fee description (for contests); may be empty
shared	boolean	Whether this market is shared with other WritersDB users
tags	array of strings	Category tags
notes	string	User notes about this market
avg_response	integer or null	Average response time in days, calculated from recorded responses
ownership	string	`owned` or `subscribed`

Create a new market

Endpoint

https://www.writersdb.com/api/markets/create

Creates a new market owned by the authenticated user.

The Request

Request type: POST

Permission required: Read+Write

Example request body

market=Strange+Horizons&web=https%3A%2F%2Fstrangehorizons.com&responsetime=12+weeks&payrate=8+cents%2Fword&simsubs=0&tags=fiction%2Csf

Request parameters

Parameter	Required	Type	Description
market	Yes	string	Name of the market
editor	No	string	Editor or contact name
web	No	string	Website URL
email	No	string	General contact email
emailsubs	No	string	Submission email address, if different from the contact email
tel	No	string	Phone number
addr1	No	string	Mailing address line 1
addr2	No	string	Mailing address line 2
city	No	string	City
state	No	string	State or province
zip	No	string	Postal code
country	No	string	Country
responsetime	No	string	Typical response time; freeform text (e.g., `"6 weeks"`, `"Quarterly"`)
payrate	No	string	Pay rate description
maxwords	No	integer	Maximum word count accepted
simsubs	No	0 or 1	Whether simultaneous submissions to other markets are accepted
multsubs	No	0 or 1	Whether multiple submissions from the same author are accepted
reprints	No	0 or 1	Whether reprints are accepted
esubs	No	0, 1, or 2	Delivery method: 0 = Postal only, 1 = Postal AND e-mail, 2 = E-mail only (default: 0)
deadline	No	date string	Submission deadline in `YYYY-MM-DD` format
entryfee	No	string	Entry fee description (for contests)
tags	No	array or comma-separated string	Tags from your existing tag list; unrecognized tags are silently ignored
notes	No	string	Free-form notes about this market
shared	No	0 or 1	Whether to share this market with other WritersDB users (default: 0)

The Response

Example response

{"id": 88}

Edit an existing market

Endpoint

https://www.writersdb.com/api/markets/edit/{id}

Updates fields on an existing market. Only fields included in the request are changed; omitted fields retain their current values. Accepts all the same parameters as Create a new market (above), all optional.

The Request

Request type: POST

Permission required: Read+Write

Example request

POST https://www.writersdb.com/api/markets/edit/88

responsetime=10+weeks&payrate=9+cents%2Fword

Request parameters

See above, under “Create a new market.”

The Response

Example response

{"success": true}

Back to Titles

Continue to Submissions

Submissions

Get a list of submissions

Endpoint

https://www.writersdb.com/api/submissions/list

Returns all submissions belonging to the authenticated user. Optionally filter by status using the status query parameter.

The Request

Request type: GET

Permission required: Read

Example request

GET https://www.writersdb.com/api/submissions/list?status=pending

Request parameters

Parameter	Required	Type	Description
status	No	string	Filter results by status. Accepted values: `pending`, `sold`, `rejected`, `withdrawn`. Omit to return all submissions.

The Response

Example response

[
  {
    "id": 101,
    "title": "The Last Signal",
    "title_id": 1,
    "market": "Clarkesworld",
    "market_id": 7,
    "datesent": "2025-03-10",
    "status": "pending",
    "custom_status_id": null,
    "status_type": null,
    "responsedate": null,
    "notes": ""
  }
]

Response fields

Field	Type	Description
id	integer	Unique identifier for the submission
title	string	Title of the submitted piece
title_id	integer	ID of the title record
market	string	Name of the market submitted to
market_id	integer	ID of the market record
datesent	date string	Date the submission was sent (`YYYY-MM-DD`)
status	string	Current status: `pending`, `sold`, `rejected`, `withdrawn`, or the name of a custom status
custom_status_id	integer or null	ID of the custom status, if one is in use; otherwise null
status_type	1, 2, or 3; or null	Category of the custom status: 1 = Pending, 2 = Closed/Success, 3 = Closed/Failure; null if a standard status is in use
responsedate	date string or null	Date a response was received (`YYYY-MM-DD`), or null if still pending
notes	string	Notes about this submission; may be empty

Get submission details

Endpoint

https://www.writersdb.com/api/submissions/detail/{id}

Returns the full detail record for a single submission.

The Request

Request type: GET

Permission required: Read

The Response

Example response

{
  "id": 101,
  "title": "The Last Signal",
  "title_id": 1,
  "market": "Clarkesworld",
  "market_id": 7,
  "datesent": "2025-03-10",
  "status": "sold",
  "custom_status_id": null,
  "status_type": null,
  "responsedate": "2025-04-01",
  "amtpaid": "336.00",
  "notes": "Accepted for June issue"
}

Response fields

Returns all the same fields as the list endpoint, plus:

Field	Type	Description
amtpaid	decimal	Payment amount received; “0.00″ if unpaid or not applicable

Send a submission

Endpoint

https://www.writersdb.com/api/submissions/send

Records a new submission of a title to a market.

The Request

Request type: POST

Permission required: Read+Write

Example request body

title_id=1&market_id=7&datesent=2025-03-10&notes=Standard+submission

Request parameters

Parameter	Required	Type	Description
title_id	Yes	integer	ID of the title being submitted
market_id	Yes	integer	ID of the market being submitted to
datesent	No	date string	Date sent in `YYYY-MM-DD` format; defaults to today
notes	No	string	Free-form notes about this submission
custom_status_id	No	integer	ID of a custom status to apply at creation time; see List custom statuses below

The Response

Example response

{"success": true}

Record a submission response

Endpoint

https://www.writersdb.com/api/submissions/response/{id}

Records a market’s response to an existing submission. Provide either status or custom_status_id, but not both.

The Request

Request type: POST

Permission required: Read+Write

Example request body

POST https://www.writersdb.com/api/submissions/response/101

status=sold&responsedate=2025-04-01&amtpaid=336.00&notes=Accepted+for+June+issue

Request parameters

Parameter	Required	Type	Description
status	Yes*	string	Response status: `pending`, `sold`, `rejected`, or `withdrawn`. Required unless `custom_status_id` is provided.
custom_status_id	Yes*	integer	ID of a custom status to apply instead of a standard status value
responsedate	No	date string	Date the response was received in `YYYY-MM-DD` format; defaults to today
amtpaid	No	decimal	Payment amount received (e.g. `336.00`); relevant when status is `sold`
notes	No	string	Notes about this response

The Response

Example response

{"success": true}

List custom statuses

Endpoint

https://www.writersdb.com/api/submissions/list_custom_statuses

Returns all custom submission statuses you have defined. Use the returned id values as custom_status_id when sending a submission or recording a response.

The Request

Request type: GET

Permission required: Read

The Response

Example response

[
  {"id": 3, "name": "Shortlisted", "status_type": 1},
  {"id": 4, "name": "R&R Requested", "status_type": 1}
]

Response fields

Field	Type	Description
id	integer	ID used to reference this custom status in other endpoints
name	string	Display name of the custom status
status_type	1, 2, or 3	Category of this custom status: 1 = Pending, 2 = Closed/Success, 3 = Closed/Failure

Back to Markets

API Documentation

Introduction

Authentication

Creating an API Key

Access Levels

Sending Your API Key

Example Request

Error Responses

Titles

Get a list of titles

The Request

The Response

Example response

Response fields

Create a new title

The Request

Example request body

Request parameters

The Response

Example response

Edit an existing title

The Request

Example request

Request parameters

The Response

Example response

Set a word count

The Request

Example request body

Request parameters

The Response

Example response

Markets

Get a list of markets

The Request

The Response

Example response

Response fields

Get market details

The Request

The Response

Example response

Response fields

Create a new market

The Request

Example request body

Request parameters

The Response

Example response

Edit an existing market

The Request

Example request

Request parameters

The Response

Example response

Submissions

Get a list of submissions

The Request

Example request

Request parameters

The Response

Example response

Response fields

Get submission details

The Request

The Response

Example response

Response fields

Send a submission

The Request

Example request body

Request parameters

The Response

Example response

Record a submission response

The Request

Example request body

Request parameters

The Response

Example response