openapi-directory

Version:

Building & bundling https://github.com/APIs-guru/openapi-directory for easy use from JS

github.com/httptoolkit/openapi-directory-js

1 lines • 104 kB

JSON

{"openapi":"3.0.0","info":{"contact":{"x-twitter":"trashnothing"},"description":"This is the REST API for [trashnothing.com](https://trashnothing.com).\n\nTo learn more about the API or to register your app for use with the API\nvisit the [trash nothing! Developer page](https://trashnothing.com/developer).\n\nNOTE: All date-time values are [UTC](https://en.wikipedia.org/wiki/Coordinated_Universal_Time)\nand are in [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601) (eg. 2019-02-03T01:23:53).\n","termsOfService":"https://trashnothing.com/tos\n","title":"trash nothing!","version":"1.0.0","x-apisguru-categories":["social"],"x-logo":{"url":"https://twitter.com/trashnothing/profile_image?size=original"},"x-origin":[{"format":"swagger","url":"https://trashnothing.com/api/trashnothing-openapi.yaml","version":"2.0"}],"x-providerName":"trashnothing.com"},"security":[{"oauth2_implicit":["basic"]},{"oauth2_code":["basic"]}],"tags":[{"description":"Retrieve and update user data.","name":"users"},{"description":"Retrieve and update posts.","name":"posts"},{"description":"Search, subscribe and unsubscribe to groups.","name":"groups"},{"description":"Upload, delete and rotate photos.","name":"photos"},{"description":"Miscellaneous functionality.","name":"misc"}],"paths":{"/feedback":{"post":{"description":"Allows users to send feedback about the trashnothing.com site or apps.","operationId":"send_feedback","requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"subject":{"description":"The subject.","type":"string"},"message":{"description":"The message.","type":"string"},"meta":{"description":"Extra information set by the client that may be useful to contextualize the feedback (eg. operating system details, browser details, app details, device details).\n","type":"string"}},"required":["subject","message"]}}}},"responses":{"200":{"description":"The feedback has been sent."}},"summary":"Send feedback","tags":["misc"]}},"/groups":{"get":{"operationId":"search_groups","parameters":[{"description":"Find groups that have the given text somewhere in their name (case insensitive).","in":"query","name":"name","required":false,"schema":{"type":"string"}},{"description":"Find groups near the given latitude and longitude.","in":"query","name":"latitude","required":false,"schema":{"type":"number"}},{"description":"Find groups near the given latitude and longitude.","in":"query","name":"longitude","required":false,"schema":{"type":"number"}},{"description":"When latitude and longitude are passed, distance can optionally be passed to only return groups within a certain distance (in kilometers) from the point specified by the latitude and longitude. The distance must be > 0 and <= 150 and will default to 100.\n","in":"query","name":"distance","required":false,"schema":{"type":"number","minimum":0,"maximum":150,"default":100}},{"description":"Find groups in the given country where country is a 2 letter country code for the country (see https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 ).\n","in":"query","name":"country","required":false,"schema":{"type":"string"}},{"description":"For countries with regions (AU, CA, GB, US), search groups in a specific region as specified by the region abbreviation. The supported regions and their abbreviations are listed below. NOTE: The region and postal_code parameters cannot be used at the same time and if both are passed then the postal_code will take priority. --- **AU** - QLD: Queensland - SA: South Australia - TAS: Tasmania - VIC: Victoria - WA: Western Australia - NT: Northern Territory - NSW: New South Wales - ACT **CA** - AB: Alberta - BC: British Columbia - MB: Manitoba - NB: New Brunswick - NL: Newfoundland and Labrador - NS: Nova Scotia - ON: Ontario - QC: Quebec - SK: Saskatchewan - PE: Prince Edward Island **GB** - E: East - EM: East Midlands - LDN: London - NE: North East - NW: North West - NI: Northern Ireland - SC: Scotland - SE: South East - SW: South West - WA: Wales - WM: West Midlands - YH: Yorkshire and the Humber **US** All 50 states and the District of Columbia are supported. For the abbreviations, see: https://github.com/jasonong/List-of-US-States/blob/master/states.csv\n","in":"query","name":"region","required":false,"schema":{"type":"string"}},{"description":"Find groups in the given postal code. Only a few countries support postal code searches (US, CA, AU, GB). The country parameter must be passed when the postal_code parameter is set. NOTE: The region and postal_code parameters cannot be used at the same time and if both are passed then the postal_code will take priority.\n","in":"query","name":"postal_code","required":false,"schema":{"type":"string"}},{"description":"The page of groups to return.","in":"query","name":"page","required":false,"schema":{"type":"integer","minimum":1,"default":1}},{"description":"The number of groups to return per page (must be >= 1 and <= 100).","in":"query","name":"per_page","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"The groups and paging data.","content":{"application/json":{"schema":{"properties":{"end_index":{"description":"The index of the last group being returned (an integer between start_index and num_groups).","type":"integer"},"groups":{"items":{"$ref":"#/components/schemas/Group"},"type":"array"},"num_groups":{"description":"The total number of groups available.","type":"integer"},"num_pages":{"description":"The total number of pages available.","type":"integer"},"page":{"description":"The page number of the groups being returned.","type":"integer"},"per_page":{"description":"The number of groups being returned per page.","type":"integer"},"start_index":{"description":"The index of the first group being returned (an integer between 1 and num_groups).","type":"integer"}},"type":"object"}}}},"400":{"description":"Missing or invalid parameters."}},"security":[{"oauth2_implicit":["basic"]},{"oauth2_code":["basic"]},{"api_key":[]}],"summary":"Search groups","tags":["groups"]}},"/groups/multiple":{"get":{"operationId":"get_groups_by_ids","parameters":[{"description":"The IDs of the groups to retrieve. If more than 20 group IDs are passed, only the first 20 groups will be returned.","in":"query","name":"group_ids","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The groups.","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/Group"},"type":"array"}}}},"400":{"description":"Missing or invalid parameters."}},"security":[{"oauth2_implicit":["basic"]},{"oauth2_code":["basic"]},{"api_key":[]}],"summary":"Retrieve multiple groups","tags":["groups"]}},"/groups/subscribe":{"post":{"description":"Request membership to one or more groups. NOTE: Any group with a has_questions field set to true will also require answers to the groups' new member questionnaire to be submitted. Groups waiting for answers will have their membership field set to 'pending-questions'. And the questionnaire that needs to be answered can be found in the membership.questionnaire field of the group.\n","operationId":"join_groups","requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"group_ids":{"description":"A comma separated list of the IDs of the groups to join.","type":"string"}},"required":["group_ids"]}}}},"responses":{"200":{"description":"The groups with updated membership data.","content":{"application/json":{"schema":{"properties":{"groups":{"description":"Updated data about the groups and the current users' membership to each group.","items":{"$ref":"#/components/schemas/Group"},"type":"array"},"over_group_limit":{"description":"When this is true, it means that some of the membership requests weren't processed in order to keep the user from going over the 12 group limit (the membership field of the groups can be used to determine which requests were processed).\n","type":"boolean"}},"type":"object"}}}},"400":{"description":"Missing or invalid parameters."},"404":{"description":"Group not found."}},"summary":"Join groups","tags":["groups"]}},"/groups/{group_id}":{"get":{"operationId":"get_group","parameters":[{"description":"The ID of the group to retrieve.","in":"path","name":"group_id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The group.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Group"}}}},"404":{"description":"Group not found."}},"security":[{"oauth2_implicit":["basic"]},{"oauth2_code":["basic"]},{"api_key":[]}],"summary":"Retrieve a group","tags":["groups"]}},"/groups/{group_id}/answers":{"post":{"description":"Submits answers to a groups' membership questionnaire. The request body should be a JSON object mapping each question from the group membership.questionnaire.questions field to an answer (eg. {\"Where do you live?\": \"New York City\"} ). All questions are required so no null or empty string answers are allowed.\n","operationId":"submit_answers","parameters":[{"description":"The group ID of the group that the user is submitting answers for.","in":"path","name":"group_id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":{"type":"string"},"type":"object"}}},"description":"A JSON object mapping each question from the group membership.questionnaire.questions field to an answer (eg. {\"Where do you live?\": \"New York City\"} ). All questions are required so no null or empty string answers are allowed.\n","required":true},"responses":{"200":{"description":"The updated group.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Group"}}}},"400":{"description":"Missing or invalid answers or questions were already answered or questions don't need to be answered."},"404":{"description":"Group not found."}},"summary":"Submit group answers","tags":["groups"]}},"/groups/{group_id}/contact":{"post":{"operationId":"contact_moderators","parameters":[{"description":"The group ID of the group whose moderators will be contacted.","in":"path","name":"group_id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"subject":{"description":"The subject of the message.","type":"string"},"message":{"description":"The body of the message.","type":"string"}},"required":["subject","message"]}}}},"responses":{"200":{"description":"Message was sent to moderators."},"400":{"description":"Missing or invalid parameters."},"404":{"description":"Group not found."}},"summary":"Contact group moderators","tags":["groups"]}},"/groups/{group_id}/unsubscribe":{"post":{"operationId":"leave_group","parameters":[{"description":"The ID of the group to leave.","in":"path","name":"group_id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Updated data about the group and the current users' membership.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Group"}}}},"400":{"description":"The current user is not an active or pending member of the given group."},"404":{"description":"Group not found."}},"summary":"Leave a group","tags":["groups"]}},"/photos":{"post":{"operationId":"upload_photo","requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"photo":{"description":"Photo to upload.","type":"string","format":"binary"},"upload_key":{"description":"A client created identifier used to associate a photo or set of photos with a post (a random number will work - must be <= 32 characters).","type":"string"},"device_pixel_ratio":{"description":"Client device pixel ratio used to determine thumbnail size (default 1.0).","type":"number","default":1}},"required":["photo","upload_key"]}}}},"responses":{"200":{"description":"Photo created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PhotoResult"}}}},"400":{"description":"Invalid upload_key or photo."}},"summary":"Create a photo","tags":["photos"]}},"/photos/{photo_id}":{"delete":{"operationId":"delete_photo","parameters":[{"in":"path","name":"photo_id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Photo deleted."},"400":{"description":"Invalid photo."},"403":{"description":"The user doesn't have permission to delete the photo."},"404":{"description":"Photo not found."}},"summary":"Delete a photo","tags":["photos"]}},"/photos/{photo_id}/rotate":{"post":{"operationId":"rotate_photo","parameters":[{"in":"path","name":"photo_id","required":true,"schema":{"type":"string"}},{"description":"Rotation in degrees - currently only 90, 180 and 270 are supported which correspond to rotate left, rotate upside down and rotate right.","in":"query","name":"degrees","required":true,"schema":{"type":"integer"}},{"description":"Client device pixel ratio used to determine thumbnail size (default 1.0).","in":"query","name":"device_pixel_ratio","required":false,"schema":{"type":"number","default":1}}],"responses":{"200":{"description":"Photo rotated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PhotoResult"}}}},"400":{"description":"Invalid photo."},"403":{"description":"The user doesn't have permission to rotate the photo."},"404":{"description":"Photo not found."}},"summary":"Rotate a photo","tags":["photos"]}},"/posts":{"get":{"description":"Only posts from the last 30 days will be returned. NOTE: Passing the latitude, longitude and radius parameters filters all posts by their location and so these parameters will temporarily override the current users' location preferences. When latitude, longitude and radius are not specified, public posts will be filtered by the current users' location preferences.\n","operationId":"get_posts","parameters":[{"description":"A comma separated list of the post types to return. The available post types are: offer, taken, wanted, received, admin\n","in":"query","name":"types","required":true,"schema":{"type":"string"}},{"description":"A comma separated list of the post sources to retrieve posts from. The available sources are: groups, trashnothing. The trashnothing source is for public posts that are posted on trash nothing but are not associated with any group. NOTE: For requests using an api key instead of oauth, passing the trashnothing source makes the latitude, longitude and radius parameters required.\n","in":"query","name":"sources","required":true,"schema":{"type":"string"}},{"description":"A comma separated list of the group IDs to retrieve posts from. This parameter is only used if the 'groups' source is passed in the sources parameter and only groups that the current user is a member of or that are open archives groups will be used (the group IDs of other groups will be silently discarded*). NOTE: For requests using an api key instead of oauth, this field is required if the 'groups' source is passed. In addition, only posts from groups that have open_archives set to true will be used (the group IDS of other groups will be silently discarded*). *To determine which group IDs were used and which were discarded, use the group_ids field in the response.\n","in":"query","name":"group_ids","required":false,"schema":{"type":"string","default":"The group IDs of every group the current user is a member of."}},{"description":"The number of posts to return per page (must be >= 1 and <= 100).","in":"query","name":"per_page","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"description":"The page of posts to return.","in":"query","name":"page","required":false,"schema":{"type":"integer","minimum":1,"default":1}},{"description":"Client device pixel ratio used to determine thumbnail size (default 1.0).","in":"query","name":"device_pixel_ratio","required":false,"schema":{"type":"number","default":1}},{"description":"The latitude of a point around which to return posts.\n","in":"query","name":"latitude","required":false,"schema":{"type":"number"}},{"description":"The longitude of a point around which to return posts.\n","in":"query","name":"longitude","required":false,"schema":{"type":"number"}},{"description":"The radius in meters of a circle centered at the point defined by the latitude and longitude parameters. When latitude, longitude and radius are passed, only posts within the circle defined by these parameters will be returned.\n","in":"query","name":"radius","required":false,"schema":{"type":"number","minimum":0,"maximum":257500}},{"description":"Only posts newer than this UTC date and time will be returned. If unset, defaults to the current date and time minus 30 days.\n","in":"query","name":"date_min","required":false,"schema":{"type":"string","format":"date-time"}},{"description":"Only posts older than this UTC date and time will be returned. If unset, defaults to the current date and time.","in":"query","name":"date_max","required":false,"schema":{"type":"string","format":"date-time"}},{"description":"Whether or not to return satisfied offer and wanted posts. This does not affect posts other than offer and wanted posts. If set to '0' (the default), only posts that are not satisfied are returned. If set to '1', only satisfied posts will be returend. If set to 'all', all posts will be returned.\n","in":"query","name":"satisfied","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"The posts and paging data.","content":{"application/json":{"schema":{"properties":{"end_index":{"description":"The index of the last post being returned (an integer between start_index and num_posts).","type":"integer"},"group_ids":{"description":"The IDs of the groups that the posts were retrieved from (will be null when no group IDs were used). These IDs may be a subset of the requested group IDs when a request includes group IDs for groups that are not open archives and that the current user is not a member of.\n","items":{"type":"string"},"type":"array"},"last_listings_view":{"description":"The UTC date and time when the current user last viewed the newest posts on the All Posts page (may be null). NOTE: For this to be accurate, clients must update the last_listings_view property of the current user every time the user is shown the newest posts on the All Posts page. NOTE: For requests using an api key instead of oauth, this field is always null.\n","format":"date-time","type":"string"},"num_pages":{"description":"The total number of pages available.","type":"integer"},"num_posts":{"description":"The total number of posts available.","type":"integer"},"page":{"description":"The page number of the posts being returned.","type":"integer"},"per_page":{"description":"The number of posts being returned per page.","type":"integer"},"posts":{"items":{"$ref":"#/components/schemas/Post"},"type":"array"},"start_index":{"description":"The index of the first post being returned (an integer between 1 and num_posts).","type":"integer"}},"type":"object"}}}},"400":{"description":"Missing or invalid parameters."}},"security":[{"oauth2_implicit":["basic"]},{"oauth2_code":["basic"]},{"api_key":[]}],"summary":"List posts","tags":["posts"]},"post":{"description":"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).\n","operationId":"submit_post","requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"group_ids":{"description":"A comma separated list of group IDs to submit the post to (if any).","type":"string"},"type":{"description":"The type of post. One of: offer, wanted\n","type":"string"},"item":{"description":"A short description of the item(s).","type":"string"},"location":{"description":"A short location description.","type":"string"},"content":{"description":"A longer description of the item(s).","type":"string"},"fair_offer":{"description":"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 ).","type":"integer"},"latitude":{"description":"The latitude corresponding to the location description provided. NOTE: This 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.\n","type":"number"},"longitude":{"description":"The longitude corresponding to the location description provided. (see the NOTE in latitude description)","type":"number"},"upload_key":{"description":"The upload_key used to upload any photos that should be attached to this post.","type":"string"},"session":{"description":"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.\n","type":"string"},"preferences":{"description":"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 only read by submit_post and never modified - it is up to the client to initialize, modify and persist the preferences object.\n","type":"string"}},"required":["type","item","location","latitude","longitude","session"]}}}},"responses":{"200":{"description":"Post submission result.","content":{"application/json":{"schema":{"properties":{"message":{"description":"Contains text describing the reason a post was not successful. Is null on success.","type":"string"},"preference_key":{"description":"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).\n","type":"string"},"result":{"description":"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 moderators of many groups may have additional automatic or manual review processes in place that can delay the publishing of a post. An error result indicates that there is an error with the post to show 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 the post (with the updated session object) to temporarily override that specific warning.\n","type":"string"},"session":{"additionalProperties":{"type":"string"},"description":"The updated session object that should override the client's copy of the session that was passed in the session parameter.","type":"object"}},"type":"object"}}}},"400":{"description":"Missing or invalid parameters."}},"summary":"Submit a post","tags":["posts"]}},"/posts/client.js":{"get":{"description":"Defines javascript functions that can be used to validate and submit posts.\n\nThe advantage of using these functions versus using the post submission endpoint directly is that\nsome of the post validation checks can be done on the client side which will be faster.\n\nNOTE: If used, this javascript file MUST be loaded dynamically for each user because the contents\nof the file are generated dynamically based on the current user. The file may be cached on a per\nuser basis based on the HTTP cache headers that are returned when the file is requested (currently\nthe cache headers specify that the file should expire after one day).\n\n\nThe following functions are available:\n\n---\n\n**window.TN.check_crossposting_restrictions(group_ids)**\n\nChecks for crossposting restrictions when the user selects more than one group to post to.\n\nParameters:\n- **group_ids** is an array of group IDs\n\nReturns an object with three properties {allowed, restricted, restrictions}.\n\n- **allowed** is an array of the group IDs from group_ids that can be crossposted to\n\n- **restricted** is an array of the group IDs from group_ids that can't be crossposted to\n\n- **restrictions** is an object mapping group IDs that have crossposting restrictions to arrays of group IDs that are restricted.\n It is useful for pinpointing why a group ID shows up in the restricted array so that users can be provided feedback\n about the reason for the crossposting restriction (eg. a message like 'group A doesn't allow crossposting to group B').\n\nFor example, given group_ids = [1, 2, 3, 4] and assuming group 1 doesn't allow posting to group 3 and group 2 doesn't allow\nposting to group 1, the returned object will be:\n\n{allowed: [4], restricted: [1, 2, 3], restrictions: {1: [3], 2: [1]}}\n\n\n---\n\n**window.TN.submit_post(args, session, preferences, callback)**\n\nSubmits a new post and performs validation checks on the post before it is accepted for submission..\n\nParameters:\n\n- **args** is an object containing data about the post being submitted and must include\n the following properties:\n\n - type: The type of post. One of: offer, wanted\n - item: A short description of the item(s).\n - location: A short location description.\n\n The following properties are optional:\n\n - content: A longer description of the item(s).\n - group_ids: An array of group IDs to submit the post to (if any).\n - fair_offer: 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 ).\n - upload_key: The key used to upload any photos that should be attached to this post.\n - latitude\n - longitude\n\n- **session** is a temporary object that is used by submit_post to store data about the submission\n process for a single post. The first time submit_post is called with a post, session should\n be a new empty object (eg. {}). The session object should be persisted until that post\n is successfully submitted and then it can be discarded so that the next post will start\n over with a new empty session object. \n\n- **preferences** is a permanent object that the client persists and modifies based on warnings returned\n by the post submission process and user input. Some post warnings passed to the callback object\n have a preference_key string property so that users can opt out of those warnings in the future.\n To save this opt-out preference, set the property indicated by the preference_key in the preferences\n object (eg. preferences[preference_key] = 1). The preferences object is only read by submit_post and\n never modified - it is up to the client to initialize, modify and persist the preferences object.\n\n- **callback** is a function used to return the result of the post submission. It is called and passed\n one argument - an object with three properties {result, message, preference_key}. The result property\n is a string that is one of: success, error, warning.\n\n A success result indicates that the post was submitted successfully. Note that posts may not\n appear instantly after submission because the moderators of many groups may have additional\n automatic or manual review processes in place that can delay the publishing of a post.\n \n An error result indicates that there is an error with the post to show the user and the message property\n will contain text describing the error.\n\n A warning result indicates that there is a warning about the post to show the user and the\n message property will contain a string describing the warning. A warning result doesn't prevent a post from\n being submitted, to continue the submission process after a warning result, just re-submit the post\n (with the updated session object) to temporarily override that specific warning.\n\n Certain types of warnings can be opted out of. These warnings will set preference_key to a string that can be \n set in the preferences object by the client to opt out of that type of warning in the future (see the description\n of the preferences parameter for more details).\n","operationId":"get_post_client_javascript","parameters":[{"description":"A comma separated list of all the group IDs that the current user is a member of. If the current user is not a member of any groups, simply pass an empty string.\n","in":"query","name":"group_ids","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The client.js javascript file."},"400":{"description":"Invalid group IDs."}},"summary":"Retrieve client.js","tags":["posts"]}},"/posts/multiple":{"get":{"operationId":"get_posts_by_ids","parameters":[{"description":"The IDs of the posts to retrieve. If more than 10 post IDs are passed, only the first 10 posts will be returned.","in":"query","name":"post_ids","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The posts.","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/Post"},"type":"array"}}}}},"security":[{"oauth2_implicit":["basic"]},{"oauth2_code":["basic"]},{"api_key":[]}],"summary":"Retrieve multiple posts","tags":["posts"]}},"/posts/search":{"get":{"description":"Searching posts takes the same arguments as listing posts except for the addition of the search and sort_by parameters. Only posts from the last 30 days will be returned.\n","operationId":"search_posts","parameters":[{"description":"The search query used to find posts.","in":"query","name":"search","required":true,"schema":{"type":"string"}},{"description":"How to sort the posts that are returned. One of: relevance, date Setting sort_by to date will sort posts from newest to oldest.\n","in":"query","name":"sort_by","required":false,"schema":{"type":"string","default":"relevance"}},{"description":"A comma separated list of the post types to return. The available post types are: offer, taken, wanted, received, admin\n","in":"query","name":"types","required":true,"schema":{"type":"string"}},{"description":"A comma separated list of the post sources to retrieve posts from. The available sources are: groups, trashnothing. The trashnothing source is for public posts that are posted on trash nothing but are not associated with any group. NOTE: For requests using an api key instead of oauth, passing the trashnothing source makes the latitude, longitude and radius parameters required.\n","in":"query","name":"sources","required":true,"schema":{"type":"string"}},{"description":"A comma separated list of the group IDs to retrieve posts from. This parameter is only used if the 'groups' source is passed in the sources parameter and only groups that the current user is a member of or that are open archives groups will be used (the group IDs of other groups will be silently discarded*). NOTE: For requests using an api key instead of oauth, this field is required if the 'groups' source is passed. In addition, only posts from groups that have open_archives set to true will be used (the group IDS of other groups will be silently discarded*). *To determine which group IDs were used and which were discarded, use the group_ids field in the response.\n","in":"query","name":"group_ids","required":false,"schema":{"type":"string","default":"The group IDs of every group the current user is a member of."}},{"description":"The number of posts to return per page (must be >= 1 and <= 100).","in":"query","name":"per_page","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"description":"The page of posts to return.","in":"query","name":"page","required":false,"schema":{"type":"integer","minimum":1,"default":1}},{"description":"Client device pixel ratio used to determine thumbnail size (default 1.0).","in":"query","name":"device_pixel_ratio","required":false,"schema":{"type":"number","default":1}},{"description":"The latitude of a point around which to return posts.\n","in":"query","name":"latitude","required":false,"schema":{"type":"number"}},{"description":"The longitude of a point around which to return posts.\n","in":"query","name":"longitude","required":false,"schema":{"type":"number"}},{"description":"The radius in meters of a circle centered at the point defined by the latitude and longitude parameters. When latitude, longitude and radius are passed, only posts within the circle defined by these parameters will be returned.\n","in":"query","name":"radius","required":false,"schema":{"type":"number","minimum":0,"maximum":257500}},{"description":"Only posts newer than this UTC date and time will be returned. If unset, defaults to the current date and time minus 30 days.\n","in":"query","name":"date_min","required":false,"schema":{"type":"string","format":"date-time"}},{"description":"Only posts older than this UTC date and time will be returned. If unset, defaults to the current date and time.","in":"query","name":"date_max","required":false,"schema":{"type":"string","format":"date-time"}},{"description":"Whether or not to return satisfied offer and wanted posts. This does not affect posts other than offer and wanted posts. If set to '0' (the default), only posts that are not satisfied are returned. If set to '1', only satisfied posts will be returend. If set to 'all', all posts will be returned.\n","in":"query","name":"satisfied","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"The posts and paging data.","content":{"application/json":{"schema":{"properties":{"end_index":{"description":"The index of the last post being returned (an integer between start_index and num_posts).","type":"integer"},"group_ids":{"description":"The IDs of the groups that the posts were retrieved from (will be null when no group IDs were used). These IDs may be a subset of the requested group IDs when a request includes group IDs for groups that are not open archives and that the current user is not a member of.\n","items":{"type":"string"},"type":"array"},"num_pages":{"description":"The total number of pages available.","type":"integer"},"num_posts":{"description":"The total number of posts available.","type":"integer"},"page":{"description":"The page number of the posts being returned.","type":"integer"},"per_page":{"description":"The number of posts being returned per page.","type":"integer"},"posts":{"items":{"$ref":"#/components/schemas/PostSearchResult"},"type":"array"},"start_index":{"description":"The index of the first post being returned (an integer between 1 and num_posts).","type":"integer"}},"type":"object"}}}},"400":{"description":"Missing or invalid parameters."}},"security":[{"oauth2_implicit":["basic"]},{"oauth2_code":["basic"]},{"api_key":[]}],"summary":"Search posts","tags":["posts"]}},"/posts/{post_id}":{"get":{"operationId":"get_post","parameters":[{"description":"The ID of the post to retrieve.","in":"path","name":"post_id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The post.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Post"}}}},"403":{"description":"The user doesn't have permission to access the post."},"404":{"description":"Post not found."}},"security":[{"oauth2_implicit":["basic"]},{"oauth2_code":["basic"]},{"api_key":[]}],"summary":"Retrieve a post","tags":["posts"]}},"/posts/{post_id}/display":{"get":{"description":"Retrieve a post and other data related to the post that is useful for displaying the post such as data about the user who posted the post and the groups the post was posted on.\n","operationId":"get_post_and_related_data","parameters":[{"description":"The ID of the post to retrieve.","in":"path","name":"post_id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The post and related data.","content":{"application/json":{"schema":{"properties":{"author":{"$ref":"#/components/schemas/User"},"author_offer_count":{"description":"Count of offer posts made by the post author in the last 30 days.","type":"integer"},"author_posts":{"description":"Other posts by the post author.","items":{"$ref":"#/components/schemas/Post"},"type":"array"},"author_wanted_count":{"description":"Count of wanted posts made by the post author in the last 30 days.","type":"integer"},"geolocate_bounds":{"$ref":"#/components/schemas/GeolocateBounds"},"groups":{"description":"The groups the post is published on.","items":{"$ref":"#/components/schemas/Group"},"type":"array"},"post":{"$ref":"#/components/schemas/Post"},"related_posts":{"description":"If the post is an offer post, this will contain taken posts that may correspond to the offer post (if any). If the post is a wanted post, this will contain received posts that may correspond to the wanted post (if any). These posts are useful to help people viewing the post decide if one or more of the items in the post is no longer available (for offer posts) or needed (for wanted posts).\n","items":{"$ref":"#/components/schemas/Post"},"type":"array"}},"type":"object"}}}},"403":{"description":"The user doesn't have permission to access the post."},"404":{"description":"Post not found."}},"security":[{"oauth2_implicit":["basic"]},{"oauth2_code":["basic"]},{"api_key":[]}],"summary":"Retrieve post display data","tags":["posts"]}},"/posts/{post_id}/flag":{"post":{"description":"Flags a post to be reviewed by the moderators.","operationId":"flag_post","parameters":[{"in":"path","name":"post_id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"reason":{"description":"The reason that this post is being flagged. Must be one of: 'spam', 'not free (for sale/trade/borrow)', 'illegal item', 'not family-friendly', 'other', 'mislabeled: is a Want', 'mislabeled: is an Offer'. NOTE: If reason is set to 'other', the details parameter is required to be set.\n","type":"string"},"details":{"description":"An explanation from the current user for why they are flagging this post. This is useful for users to provide evidence or explain why there is a problem with the post. NOTE: If reason is set to 'other', details are required.\n","type":"string"}},"required":["reason"]}}}},"responses":{"200":{"description":"The post has been flagged."},"400":{"description":"Invalid reason parameter or missing details."},"404":{"description":"Post not found."}},"summary":"Flag a post","tags":["posts"]}},"/posts/{post_id}/geolocate":{"put":{"description":"Map a post to a specific location when the post is missing a location or has an incorrect location.","operationId":"geolocate_post","parameters":[{"description":"The ID of the post to geolocate.","in":"path","name":"post_id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"latitude":{"type":"number"},"longitude":{"type":"number"},"location":{"description":"A location name corresponding to the given latitude and longitude. Usually this is either a location included somewhere in the post title or content or a location description typed or selected by the user who is mapping the post.\n","type":"string"}},"required":["latitude","longitude"]}}}},"responses":{"200":{"description":"The updated post.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Post"}}}},"400":{"description":"Invalid latitude or longitude."},"403":{"description":"The user doesn't have permission to access the post."},"404":{"description":"Post not found."}},"summary":"Map a post","tags":["posts"]}},"/posts/{post_id}/reply":{"post":{"description":"Send a reply to a post from the current user to the post author.","operationId":"reply_to_post","parameters":[{"description":"The ID of the post to reply to.","in":"path","name":"post_id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"message":{"description":"The message to send to the post author.","type":"string"},"send_copy":{"description":"If set to 1, a copy of the reply will be emailed to the current user.","type":"integer"}},"required":["message"]}}}},"responses":{"200":{"description":"The reply has been sent."},"400":{"description":"Missing message parameter or post has been satisfied."},"403":{"description":"The user doesn't have permission to reply to the post."},"404":{"description":"Post not found."}},"summary":"Reply to a post","tags":["posts"]}},"/posts/{post_id}/satisfy":{"put":{"description":"Mark an offer or wanted post by the current user as satisfied (eg. an offer has been taken or a wanted has been received).","operationId":"satisfy_post","parameters":[{"description":"The ID of the post to satisfy.","in":"path","name":"post_id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"summary":{"description":"If the post contains multiple items and not every item has been taken or received, pass a short summary of the items that have been so that the post will be updated to reflect which items are still being offered or request. Once all items in the post have been taken or received, this endpoint should be called with no summary passed so that the post will be removed from the listings.\n","type":"string"}}}}}},"responses":{"200":{"description":"The updated post.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Post"}}}},"400":{"description":"Invalid summary or the post is not an offer or wanted post."},"403":{"description":"The user doesn't have permission to access the post."},"404":{"description":"Post not found."}},"summary":"Satisfy a post","tags":["posts"]}},"/posts/{post_id}/share":{"get":{"description":"Retrieve text and html content useful for sharing a post by email.","operationId":"get_post_share_content","parameters":[{"description":"The ID of the post to share.","in":"path","name":"post_id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Email subject, text body and html body for sharing a post by email.","content":{"application/json":{"schema":{"properties":{"html":{"description":"Email body as html.","type":"string"},"subject":{"description":"Email subject line text.","type":"string"},"text":{"description":"Email body as plain text.","type":"string"}},"type":"object"}}}}},"summary":"Retrieve post share content","tags":["posts"]},"post":{"description":"Forwards a copy of the post to the current user so that they can forward it to friends.","operationId":"share_post","parameters":[{"description":"The ID of the post to share.","in":"path","name":"post_id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Post shared."},"403":{"description":"The user doesn't have permission to access the post."},"404":{"description":"Post not found."}},"summary":"Share a post","tags":["posts"]}},"/users/me":{"get":{"operationId":"get_current_user","responses":{"200":{"description":"User data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CurrentUser"}}}},"404":{"description":"User not found."}},"summary":"Retrieve current user","tags":["users"]},"put":{"description":"Update the current user. All fields are optional so requests can update just one or multiple user properties at a time.\n","operationId":"update_current_user","requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"firstname":{"description":"The first name of the user.","type":"string"},"lastname":{"description":"The last name of the user.","type":"string"},"public_name":{"description":"Whether or not the users' first and last name will be visible to other users. Set to 1 to enable and 0 to disable.\n","type":"integer"},"digest":{"description":"The frequency of digest emails sent to this user. One of: daily, 12_hours, 8_hours, 6_hours, 4_hours, 2_hours, hourly To disable digests, set this to an empty string. NOTE: A weekly option with the value 'weekly' will probably be added in the future so clients should recognize weekly as a valid value that can be displayed and set if it is ever returned.\n","type":"string"},"post_reminders":{"description":"Whether or not the user will receive post reminder emails (to remind them to update or repost their posts). Set to 1 to enable and 0 to disable.\n","type":"integer"},"password":{"description":"A new password for the users' account. When setting a new password, the old_password parameter must be passed and set to the users' current password. NOTE: The password and old_password properties can NOT be used when the user property has_password is false. Instead, use the password reset endpoint to have a new password emailed to the user.\n","type":"string"},"old_password":{"description":"The users current password. This is required when the user is changing their password.","type":"string"},"profile_image_source":{"description":"The source of the users' profile image. The values this can be set to change dynamically based on the users' account. To get the values that can be used, use the source properties returned by the profile images endpoint.\n","type":"string"},"last_listings_view":{"description":"The UTC date and time when the user last viewed the newest posts on the All Posts page.","type":"string","format":"date-time"},"filter_group_posts_by_location":{"description":"Whether or not group posts should be filtered by their location to only include posts defined by the users' location field. Set to 1 to enable and 0 to disable.\n","type":"integer"},"public_post_sources":{"description":"A comma separated list of the sources to show public posts from. Currently only 'trashnothing' is supported.\nIf not passed, all sources will be enabled.\nIf set to an empty string, no sources will be enabled which effectively disables public posts for the user so that the user will only see posts from the groups they are a member of.\n","type":"string"}}}}}},"responses":{"200":{"description":"The updated user data.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CurrentUser"}}}},"400":{"description":"Invalid parameter."}},"summary":"Update current user","tags":["users"]}},"/users/me/alerts":{"get":{"operationId":"get_alerts","responses":{"200":{"description":"The users alerts.","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/Alert"},"type":"array"}}}}},"summary":"List current users' email alerts","tags":["users"]},"put":{"operationId":"create_alert","requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"search":{"description":"When a post matches this search query, an email alert will be sent. Must have a length >= 2 and < 255 characters.","type":"string"},"types":{"description":"A comma separated list of the post types that the alert should match against. The available post types are: offer, wanted\n","type":"string"}},"required":["search","types"]}}}},"responses":{"200":{"description":"The new alert.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Alert"}}}},"400":{"description":"Missing or invalid parameters or maximum number of alerts reached."}},"summary":"Create an email alert","tags":["users"]}},"/users/me/alerts/{alert_id}":{"delete":{"operationId":"delete_alert","parameters":[{"description":"The ID of the email alert to delete.","in":"path","name":"alert_id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Alert deleted."},"403":{"description":"The user doesn't have permission to access the alert."},"404":{"description":"Alert not found."}},"summary":"Delete an email alert","tags":["users"]}},"/users/me/emails":{"get":{"operationId":"get_emails","responses":{"200":{"description":"The users emails addresses.","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/Email"},"type":"array"}}}}},"summary":"List email addresses","tags":["users"]},"put":{"description":"Add a new email address to the current users' account. The first time an email address is added to a users account, a verification link will be sent to the email address to verify the address.\n","operationId":"add_email","requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"address":{"description":"The email address to add.","type":"string"}},"required":["address"]}}}},"responses":{"200":{"description":"The new email.","conten