Zulip drafts API
The drafts API from Zulip — 4 operation(s) for drafts.
OpenAPI Specification
openapi: 3.0.1
info:
version: 1.0.0
title: Zulip REST authentication drafts API
description: 'Powerful open source group chat
'
contact:
url: https://zulip.com
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://{subdomain}.zulipchat.com/api/v1
variables:
subdomain:
default: example
- url: '{server}/api/v1'
variables:
server:
default: https://
- url: https://chat.zulip.org/api/v1
- url: http://localhost:9991/api/v1
- url: http://{subdomain}.testserver/json
security:
- basicAuth: []
tags:
- name: drafts
paths:
/drafts:
get:
operationId: get-drafts
tags:
- drafts
summary: Get drafts
description: 'Fetch all drafts for the current user.
'
responses:
'200':
description: Success.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonSuccessBase'
- additionalProperties: false
properties:
result: {}
msg: {}
ignored_parameters_unsupported: {}
count:
type: integer
description: 'The number of drafts the user currently has. Also the
number of drafts returned under "drafts".
'
example: 3
drafts:
type: array
description: 'Returns all of the current user''s drafts, in order of last edit time
(with the most recently edited draft appearing first).
'
items:
$ref: '#/components/schemas/Draft'
example:
result: success
msg: ''
count: 3
drafts:
- id: 1
type: stream
to:
- 3
topic: sync drafts
content: Let's add backend support for syncing drafts.
timestamp: 1595479019
- id: 2
type: private
to:
- 4
topic: ''
content: What if we made it possible to sync drafts in Zulip?
timestamp: 1595479019
- id: 3
type: private
to:
- 4
- 10
topic: ''
content: What if we made it possible to sync drafts in Zulip?
timestamp: 1595479019
post:
operationId: create-drafts
tags:
- drafts
summary: Create drafts
description: 'Create one or more drafts on the server. These drafts will be automatically
synchronized to other clients via `drafts` events.
'
requestBody:
required: false
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
drafts:
description: 'A JSON-encoded list of containing new draft objects.
'
type: array
items:
$ref: '#/components/schemas/Draft'
example:
- type: stream
to:
- 1
topic: questions
content: What are the contribution guidelines for this project?
timestamp: 1595479019
encoding:
drafts:
contentType: application/json
responses:
'200':
description: Success.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonSuccessBase'
- additionalProperties: false
properties:
result: {}
msg: {}
ignored_parameters_unsupported: {}
ids:
type: array
description: 'An array of the IDs for the drafts that were just created in the same
order as they were submitted.
'
items:
type: integer
example:
result: success
msg: ''
ids:
- 1
- 2
- 3
'400':
description: Bad request.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/CodedError'
- description: 'JSON response for when a draft targeted towards a channel does not specify
exactly one channel ID:
'
example:
code: BAD_REQUEST
msg: Must specify exactly 1 channel ID for channel messages
result: error
/drafts/{draft_id}:
patch:
operationId: edit-draft
tags:
- drafts
summary: Edit a draft
description: 'Edit a draft on the server. The edit will be automatically
synchronized to other clients via `drafts` events.
'
parameters:
- name: draft_id
in: path
schema:
type: integer
description: 'The ID of the draft to be edited.
'
required: true
example: 2
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
draft:
allOf:
- $ref: '#/components/schemas/Draft'
- description: 'A JSON-encoded object containing a replacement draft object for this ID.
'
example:
type: stream
to:
- 1
topic: questions
content: how tough is a Lamy Safari?
timestamp: 1595479019
required:
- draft
encoding:
draft:
contentType: application/json
responses:
'200':
$ref: '#/components/responses/SimpleSuccess'
'404':
description: Not Found.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/CodedError'
- description: 'A typical failed JSON response for when no draft exists with
the provided ID:
'
example:
code: BAD_REQUEST
result: error
msg: Draft does not exist
delete:
operationId: delete-draft
tags:
- drafts
summary: Delete a draft
description: 'Delete a single draft from the server. The deletion will be automatically
synchronized to other clients via a `drafts` event.
'
parameters:
- name: draft_id
in: path
schema:
type: integer
description: 'The ID of the draft you want to delete.
'
required: true
example: 1
responses:
'200':
$ref: '#/components/responses/SimpleSuccess'
'404':
description: Not Found.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/CodedError'
- description: 'A typical failed JSON response for when no draft exists with
the provided ID:
'
example:
code: BAD_REQUEST
result: error
msg: Draft does not exist
/saved_snippets:
get:
operationId: get-saved-snippets
tags:
- drafts
summary: Get all saved snippets
description: 'Fetch all the saved snippets for the current user.
**Changes**: New in Zulip 10.0 (feature level 297).
'
responses:
'200':
description: Success.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonSuccessBase'
- additionalProperties: false
properties:
result: {}
msg: {}
ignored_parameters_unsupported: {}
saved_snippets:
type: array
description: 'An array of dictionaries containing data on all of the current user''s
saved snippets.
'
items:
$ref: '#/components/schemas/SavedSnippet'
example:
result: success
msg: ''
saved_snippets:
- id: 1
title: Example
content: Welcome to the organization.
date_created: 1681662420
post:
operationId: create-saved-snippet
tags:
- drafts
summary: Create a saved snippet
description: 'Create a new saved snippet for the current user.
**Changes**: New in Zulip 10.0 (feature level 297).
'
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
title:
type: string
description: 'The title of the saved snippet.
'
example: Example title
content:
type: string
description: 'The content of the saved snippet in [Zulip-flavored Markdown](/help/format-your-message-using-markdown) format.
Clients should insert this content into a message when using
a saved snippet.
'
example: Welcome to the organization.
required:
- title
- content
responses:
'200':
description: Success.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonSuccessBase'
- additionalProperties: false
properties:
result: {}
msg: {}
ignored_parameters_unsupported: {}
saved_snippet_id:
type: integer
description: 'The unique ID of the saved snippet created.
'
example:
result: success
msg: ''
saved_snippet_id: 1
'400':
description: Bad request.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/CodedError'
- example:
code: BAD_REQUEST
msg: Title cannot be empty.
result: error
description: 'A typical failed JSON response for when either title or content is
empty:
'
/saved_snippets/{saved_snippet_id}:
patch:
operationId: edit-saved-snippet
tags:
- drafts
summary: Edit a saved snippet
description: 'Edit a saved snippet for the current user.
**Changes**: New in Zulip 10.0 (feature level 368).
'
parameters:
- name: saved_snippet_id
in: path
schema:
type: integer
description: 'The ID of the saved snippet to edit.
'
required: true
example: 3
requestBody:
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
title:
type: string
description: 'The title of the saved snippet.
'
example: Welcome message
content:
type: string
description: 'The content of the saved snippet in the original [Zulip-flavored Markdown](/help/format-your-message-using-markdown) format.
Clients should insert this content into a message when using
a saved snippet.
'
example: Welcome to the organization.
responses:
'200':
$ref: '#/components/responses/SimpleSuccess'
'404':
description: Not Found.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/CodedError'
- description: 'A typical failed JSON response for when no saved snippet exists
with the provided ID:
'
example:
code: BAD_REQUEST
result: error
msg: Saved snippet does not exist.
delete:
operationId: delete-saved-snippet
tags:
- drafts
summary: Delete a saved snippet
description: 'Delete a saved snippet.
**Changes**: New in Zulip 10.0 (feature level 297).
'
parameters:
- name: saved_snippet_id
in: path
schema:
type: integer
description: 'The ID of the saved snippet to delete.
'
required: true
example: 2
responses:
'200':
$ref: '#/components/responses/SimpleSuccess'
'404':
description: Not Found.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/CodedError'
- description: 'A typical failed JSON response for when no saved snippet exists
with the provided ID:
'
example:
code: BAD_REQUEST
result: error
msg: Saved snippet does not exist.
components:
schemas:
JsonSuccessBase:
description: '**Changes**: As of Zulip 7.0 (feature level 167), if any
parameters sent in the request are not supported by this
endpoint, a successful JSON response will include an
[`ignored_parameters_unsupported`][ignored_params] array.
A typical successful JSON response may look like:
[ignored_params]: /api/rest-error-handling#ignored-parameters
'
allOf:
- $ref: '#/components/schemas/JsonResponseBase'
- required:
- result
- msg
properties:
result:
enum:
- success
msg:
type: string
ignored_parameters_unsupported:
$ref: '#/components/schemas/IgnoredParametersUnsupported'
SavedSnippet:
type: object
description: 'Object containing the details of the saved snippet.
'
additionalProperties: false
properties:
id:
type: integer
description: 'The unique ID of the saved snippet.
'
title:
type: string
description: 'The title of the saved snippet.
'
content:
type: string
description: 'The content of the saved snippet in [Zulip-flavored Markdown](/help/format-your-message-using-markdown) format.
Clients should insert this content into a message when using
a saved snippet.
'
date_created:
type: integer
description: 'The UNIX timestamp for when the saved snippet was created, in
UTC seconds.
'
JsonSuccess:
allOf:
- $ref: '#/components/schemas/JsonSuccessBase'
- additionalProperties: false
properties:
result: {}
msg: {}
ignored_parameters_unsupported: {}
example:
msg: ''
result: success
IgnoredParametersUnsupported:
type: array
items:
type: string
description: 'An array of any parameters sent in the request that are not
supported by the endpoint.
See [error handling](/api/rest-error-handling#ignored-parameters) documentation
for details on this and its change history.
'
JsonResponseBase:
type: object
properties:
result:
type: string
Draft:
type: object
description: 'A dictionary for representing a message draft.
'
properties:
id:
type: integer
readOnly: true
description: 'The unique ID of the draft.
'
type:
type: string
description: 'The type of the draft. Either unaddressed (empty string), `"stream"`,
or `"private"` (for one-on-one and group direct messages).
'
enum:
- ''
- stream
- private
to:
type: array
description: 'An array of the tentative target audience IDs. For channel
messages, this should contain exactly 1 ID, the ID of the
target channel. For direct messages, this should be an array
of target user IDs. For unaddressed drafts, this is ignored,
and clients should send an empty array.
'
items:
type: integer
topic:
type: string
description: 'For channel message drafts, the tentative topic name. For direct
or unaddressed messages, this will be ignored and should ideally
be the empty string. Should not contain null bytes.
'
content:
type: string
description: 'The body of the draft. Should not contain null bytes.
'
timestamp:
type: integer
description: 'A Unix timestamp (seconds only) representing when the draft was
last edited. When creating a draft, this key need not be present
and it will be filled in automatically by the server.
'
example: 1595479019
additionalProperties: false
required:
- type
- to
- topic
- content
CodedError:
allOf:
- $ref: '#/components/schemas/CodedErrorBase'
- additionalProperties: false
properties:
result: {}
msg: {}
code: {}
CodedErrorBase:
allOf:
- $ref: '#/components/schemas/JsonResponseBase'
- required:
- result
- msg
- code
properties:
result:
enum:
- error
msg:
type: string
code:
type: string
description: 'A string that identifies the error.
'
responses:
SimpleSuccess:
description: Success.
content:
application/json:
schema:
$ref: '#/components/schemas/JsonSuccess'
securitySchemes:
BasicAuth:
type: http
scheme: basic
description: 'Basic authentication, with the user''s email as the username, and the API
key as the password. The API key can be fetched using the
`/fetch_api_key` or `/dev_fetch_api_key` endpoints.
'