Submit a post

POST

/posts

posts

Submits a new post.

NOTE: An alternate way to submit posts that does quicker client side validation is to use the script served by the API at the /posts/client.js endpoint (see the description of the /posts/client.js endpoint for usage instructions).

Request Example

Shell

JavaScript

Java

Swift

curl --location --request POST 'https://trashnothing.com/api/v1.2/posts' \
--form 'location=""' \
--form 'session=""' \
--form 'title=""' \
--form 'type=""'

Response Example

200 - Example 1

{
    "identifier": "string",
    "message": "string",
    "preference_key": "string",
    "result": "string",
    "session": {
        "property1": "string",
        "property2": "string"
    }
}

Request

Body Params multipart/form-data

content

string

optional

A longer description of the item(s).

expires_in

string

optional

When the post should expire. Defaults to 90 days. Any amount of time from 1 hour to 90 days can be provided. To pass a number of hours, provide the number of hours prefixed by 'h' (eg. 1hr 24hr). To pass a number of days, provide the number of days prefixed by 'd' (eg. 1d 90d).

Note that posts may not appear instantly after submission because the volunteer moderators of many groups may have additional automatic or manual review processes in place that can cause delays. So with short expirations (eg. < 8 hours), there is a chance that the post may expire before it's approved and so it will never be published.

fair_offer

string

optional

If set to 1, the post will be posted with the Fair Offer Policy (only valid for offer posts - see https://trashnothing.com/fair_offer_policy ).

group_ids

string

optional

A comma separated list of group IDs to submit the post to (if any).

latitude

string

optional

The latitude corresponding to the location description provided.

If latitude and longitude are not provided, an attempt will be made to automatically geocode the location. If the location is unable to be geocoded, the post will be rejected* and will have to be resubmitted with a latitude and longitude corresponding to the location or resubmitted with a different location that can be automatically geocoded.

NOTE: The latitude and longitude should NOT be the users' exact location because we don't want to publicize their exact location unless their location description is their full address (which is not recommended).

*When a post is rejected because it can't be geocoded, the returned error will have its identifier property set to 'unknown-location'.

location

string

required

A short location description.

longitude

string

optional

The longitude corresponding to the location description provided. (see the NOTE in latitude description)

photo_ids

string

optional

A comma separated list of the IDs of the photos that should be attached to this post.

preferences

string

optional

A JSON string representing a permanent object that the client persists and modifies based on warnings returned by the post submission process and user input. Some warnings returned after submitting a post have a preference_key string property so that users can opt out of those warnings in the future. To save this opt-out preference, set the property indicated by the preference_key in the preferences object (eg. preferences[preference_key] = 1). The preferences object is never modified by the server - it is up to the client to initialize, modify and persist the preferences object.

session

string

required

A JSON string representing a temporary object that is used to store data about the submission process for a single post. The first time a post is submitted, session should be a new empty object (eg. '{}'). The session object should be persisted by the client until that post is successfully submitted and then it can be discarded so that the next post will start over with a new empty session object. Every time a post is submitted and the response indicates that the submission was not successful, the session object returned in the response should override the clients copy of the session.

title

string

required

A short description of the item(s).

type

string

required

The type of post. One of: offer, wanted

Responses

🟢200Post submission result.

application/json

Body

identifier

string

optional

When an error or warning is returned, this will contain a short string representing the type of error or warning that occurred. Is null on success.

message

string

optional

Contains text describing the reason a post was not successful. Is null on success.

preference_key

string

optional

Certain types of warnings can be opted out of. These warnings will set preference_key to a string that can be set in the preferences object by the client to opt out of that type of warning in the future (see the description of the preferences parameter for more details). Is null for errors, success and warnings that can't be opted out of.

result

string

optional

One of: success, error, warning.

A success result indicates that the post was submitted successfully. Note that posts may not appear instantly after submission because the volunteer moderators of many groups may have additional automatic or manual review processes in place that can cause delays.

An error result indicates that there is an error with the post that should be shown to the user and the message property will contain text describing the error.

A warning result indicates that there is a warning about the post to show the user and the message property will contain a string describing the warning. A warning result doesn't prevent a post from being submitted, to continue the submission process after a warning result, just re-submit (with the updated session object) to temporarily override that specific warning.

session

object

optional

The updated session object that should override the client's copy of the session that was passed in the session parameter. Is null on success.

Additional properties

string

optional

🟠400Missing or invalid parameters.

Modified at 2022-09-11 18:59:48

List posts

List all posts