zulip/templates/zerver/api/arguments.json

{
    "private-message.md": [
        {
            "argument": "type",
            "description": "The type of message to be sent. `private` for a private message and `stream` for a [stream message](/api/stream-message).",
            "required": true,
            "example": "private"
        },
        {
            "argument": "to",
            "description": "A JSON-encoded list containing the usernames of the recipients.",
            "required": true,
            "example": "wdaher@example.com"
        },
        {
            "argument": "content",
            "description": "The content of the message. Maximum message size of 10000 bytes.",
            "required": true,
            "example": "Hello"
        }
    ],
    "stream-message.md": [
        {
            "argument": "type",
            "description": "The type of message to be sent. `stream` for a stream message and `private` for a [private message](/api/private-message).",
            "required": true,
            "example": "stream"
        },
        {
            "argument": "to",
            "description": "A string identifying the stream.",
            "required": true,
            "example": "Denmark"
        },
        {
            "argument": "subject",
            "description": "The topic of the message. Only required if `type` is `stream`. Defaults to `None`. Maximum length of 60 characters.",
            "required": false,
            "example": "Castle"
        },
        {
            "argument": "content",
            "description": "The content of the message. Maximum message size of 10000 bytes.",
            "required": true,
            "example": "Hello"
        }
    ],
    "get-all-streams.md": [
        {
            "argument": "include_public",
            "description": "Include all public streams. Default is `True`.",
            "required": false,
            "example": "`True` or `False`"
        },
        {
            "argument": "include_subscribed",
            "description": "Include all streams that the user is subscribed to. Default is `True`.",
            "required": false,
            "example": "`True` or `False`"
        },
        {
            "argument": "include_all_active",
            "description": "Include all active streams. The user must have administrative privileges to use this parameter. Default is `False`.",
            "required": false,
            "example": "`True` or `False`"
        },
        {
            "argument": "include_default",
            "description": "Include all default streams for the user's realm. Default is `False`.",
            "required": false,
            "example": "`True` or `False`"
        }
    ],
    "get-stream-id.md": [
        {
            "argument": "stream",
            "description": "The name of the stream to retrieve the ID for.",
            "required": true,
            "example": "Denmark"
        }
    ],
    "render-message.md": [
        {
            "argument": "content",
            "description": "The content of the message.",
            "required": true,
            "example": "**foo**"
        }
    ],
    "get-all-users.md": [
        {
            "argument": "client_gravatar",
            "description": "The `client_gravatar` field is set to `True` if clients can compute their own gravatars. Default is `False`.",
            "required": false,
            "example": "`True` or `False`"
        }
    ],
    "register-queue.md": [
        {
            "argument": "apply_markdown",
            "description": "Set to `True` if you would like the content to be rendered in HTML format (by default, the API returns the raw text that the user entered)",
            "required": false,
            "example": "`True` or `False`"
        },
        {
            "argument": "client_gravatar",
            "description": "The `client_gravatar` field is set to `True` if clients can compute their own gravatars. Default is `False`.",
            "required": false,
            "example": "`True` or `False`"
        },
        {
            "argument": "event_types",
            "description": "A JSON-encoded array indicating which types of events you're interested in. Values that you might find useful include: <br/> <br/> * **message** (messages), <br/> * **subscription** (changes in your subscriptions), <br/> * **realm_user** (changes in the list of users in your realm) <br/> <br/> If you do not specify this argument, you will receive all events, and have to filter out the events not relevant to your client in your client code. For most applications, one is only interested in messages, so one specifies: `event_types=['message']`",
            "required": false,
            "example": "event_types=['message']"
        },
        {
            "argument": "all_public_streams",
            "description": "Set to `True` if you would like to receive events that occur within all public streams. Default is `None`.",
            "required": false,
            "example": "`True` or `False`"
        },
        {
            "argument": "include_subscribers",
            "description": "Set to `True` if you would like to receive events that include the subscribers for each stream. Default is `False`.",
            "required": false,
            "example": "`True` or `False`"
        },
        {
            "argument": "fetch_event_types",
            "description": "Same as the `event_types` argument except that the values in `fetch_event_types` are used to fetch initial data. If `fetch_event_types` is not provided, `event_types` is used and if `event_types` is not provided, this argument defaults to `None`.",
            "required": false,
            "example": "event_types=['message']"
        },
        {
            "argument": "narrow",
            "description": "A JSON-encoded array of length 2 indicating the narrow for which you'd like to receive events for. For instance, to receive events for the stream `Denmark`, you would specify `narrow=['stream', 'Denmark']`. Another example is `narrow=['is', 'private']` for private messages. Default is `[]`.",
            "required": false,
            "example": "narrow=['stream', 'Denmark']"
        }
    ],
    "get-events-from-queue.md": [
        {
            "argument": "queue_id",
            "description": "The ID of a queue that you registered via `POST /api/v1/register`(see [Register a queue](/api/register-queue)).",
            "required": false,
            "example": "1375801870:2942"
        },
        {
            "argument": "last_event_id",
            "description": "The highest event ID in this queue that you've received and wish to acknowledge. See the [code for `call_on_each_event`](https://github.com/zulip/python-zulip-api/blob/master/zulip/zulip/__init__.py) in the [zulip Python module](https://github.com/zulip/python-zulip-api) for an example implementation of correctly processing each event exactly once.",
            "required": false,
            "example": "-1"
        },
        {
            "argument": "dont_block",
            "description": "Set to `True` if the client is requesting a nonblocking reply. If not specified, the request will block until either a new event is available or a few minutes have passed, in which case the server will send the client a heartbeat event. Default is `False`.",
            "required": false,
            "example": "`True` or `False`"
        }
    ],
    "call_on_each_event": [
        {
            "argument": "narrow",
            "description": "A JSON-encoded array of length 2 indicating the narrow for which you'd like to receive events for. For instance, to receive events for the stream `Denmark`, you would specify `narrow=['stream', 'Denmark']`. Another example is `narrow=['is', 'private']` for private messages. Default is `[]`.",
            "required": false,
            "example": "narrow=['stream', 'Denmark']"
        },
        {
            "argument": "event_types",
            "description": "A JSON-encoded array indicating which types of events you're interested in. Values that you might find useful include: <br/> <br/> * **message** (messages), <br/> * **subscription** (changes in your subscriptions), <br/> * **realm_user** (changes in the list of users in your realm)<br/> <br/> If you do not specify this argument, you will receive all events, and have to filter out the events not relevant to your client in your client code. For most applications, one is only interested in messages, so one specifies: `event_types=['message']`",
            "required": false,
            "example": "event_types=['message']"
        }
    ],
    "delete-queue.md": [
        {
            "argument": "queue_id",
            "description": "The ID of a queue that you registered via `POST /api/v1/register`(see [Register a queue](/api/register-queue) and [Get events from queue](/api/get-events-from-queue)).",
            "required": true,
            "example": "1375801870:2942"
        }
    ],
    "update-message.md": [
        {
            "argument": "message_id",
            "description": "The ID of the message that you wish to edit/update.",
            "required": true,
            "example": "134"
        },
        {
            "argument": "subject",
            "description": "The topic of the message. Only required for a stream message. Defaults to `None`. Maximum length of 60 characters.",
            "required": false,
            "example": "Castle"
        },
        {
            "argument": "content",
            "description": "The content of the message. Maximum message size of 10000 bytes.",
            "required": false,
            "example": "Hello"
        },
        {
            "argument": "propagate_mode",
            "description": "In the case of a topic update, `propagate_mode` is a value specifying whether the topic of any other messages in the same conversation would be updated or not. Possible values include: <br/> <br/> * **change_one** (Default): Update the topic only of the message with the given `message_id`. <br/> * **change_all**: Update the topic of all messages with the same previous topic as the message with `message_id`. <br/> * **change_later**: Update the topic of the message with `message_id` *and* update the topic of the messages with the same previous topic after it.",
            "required": false,
            "example": "change_all"
        }
    ],
    "add-subscriptions.md": [
        {
            "argument": "subscriptions",
            "description": "A list of dictionaries, where each dictionary contains key/value pairs specifying a particular stream to subscribe to. **Note**: This argument is called `streams` and not `subscriptions` in our Python API.",
            "required": true,
            "example": "[{'name': 'Verona'}]"
        },
        {
            "argument": "invite_only",
            "description": "A boolean specifying whether the streams specified in `subscriptions` are invite-only or not. Default is `False`.",
            "required": false,
            "example": "`True` or `False`"
        },
        {
            "argument": "announce",
            "description": "If `announce` is `True` and one of the streams specified in `subscriptions` has to be created (i.e. doesn't exist to begin with), an announcement will be made notifying that a new stream was created.",
            "required": false,
            "example": "`True` or `False`"
        },
        {
            "argument": "principals",
            "description": "A list of email addresses of the users that will be subscribed to the streams specified in the `subscriptions` argument. Default is `[]`. If not provided, then the requesting user/bot is subscribed.",
            "required": false,
            "example": "['ZOE@zulip.com']"
        },
        {
            "argument": "authorization_errors_fatal",
            "description": "A boolean specifying whether authorization errors (such as when the requesting user is not authorized to access a private stream) should be considered fatal or not. Default is `True`, in which case an authorization error is reported as such. When set to `False`, the returned JSON payload indicates that there was an authorization error, but the response is still considered a successful one.",
            "required": false,
            "example": "`True` or `False`"
        }
    ],
    "create-user.md": [
        {
            "argument": "email",
            "description": "The email address of the new user.",
            "required": true,
            "example": "newbie@zulip.com"
        },
        {
            "argument": "password",
            "description": "The password of the new user.",
            "required": true,
            "example": "abdec@7982"
        },
        {
            "argument": "full_name",
            "description": "The full name of the new user.",
            "required": true,
            "example": "John Smith"
        },
        {
            "argument": "short_name",
            "description": "The short name of the new user.",
            "required": true,
            "example": "jsmith"
        }
    ],
    "remove-subscriptions.md": [
        {
            "argument": "subscriptions",
            "description": "A list of stream names to unsubscribe from. This argument is called `streams` in our Python API.",
            "required": true,
            "example": "['Verona', 'Denmark']"
        },
        {
            "argument": "principals",
            "description": "A list of email addresses of the users that will be unsubscribed from the streams specified in the `subscriptions` argument. Default is `None`. If not provided, then the requesting user/bot is unsubscribed.",
            "required": false,
            "example": "['ZOE@zulip.com']"
        }
    ],
    "upload-file.md": [
        {
            "argument": "file",
            "description": "File to be uploaded.",
            "required": true,
            "example": "See code examples above."
        }
    ]
}